Skip to content

Commit a0a512e

Browse files
committed
chore(documentation): add new reference section
1 parent 4efa869 commit a0a512e

33 files changed

+1322
-148
lines changed

documentation/docs/.vitepress/config.mjs

Lines changed: 69 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -21,14 +21,19 @@ export default defineConfig({
2121
],
2222
themeConfig: {
2323
// https://vitepress.dev/reference/default-theme-config
24-
logo: '/logo.png',
24+
logo: '/logo-min.png',
2525

2626
nav: [
2727
{
2828
text: 'Guide',
2929
link: '/guide/what-is-simplew',
3030
activeMatch: '/guide/'
3131
},
32+
{
33+
text: 'Reference',
34+
link: '/reference/simplewserver',
35+
activeMatch: '/reference/'
36+
},
3237
//{ text: '📖✨ Features', link: '/features' },
3338
{
3439
text: 'v14.0.1',
@@ -41,48 +46,69 @@ export default defineConfig({
4146
sidebar: {
4247

4348
'/guide/': [
44-
{
45-
text: 'Introduction',
46-
items: [
47-
{ text: 'What is SimpleW?', link: '/guide/what-is-simplew' },
48-
{ text: 'Getting Started', link: '/guide/getting-started' },
49-
// { text: 'Performances', link: '/guide/performances' },
50-
]
51-
},
52-
{
53-
text: 'Serve API',
54-
items: [
55-
{ text: 'Basic', link: '/guide/api-basic' },
56-
{ text: 'Routing', link: '/guide/api-routes' },
57-
{ text: 'Response', link: '/guide/api-response' },
58-
{ text: 'Request', link: '/guide/api-request' },
59-
{ text: 'Callback', link: '/guide/api-callback' },
60-
]
61-
},
62-
{
63-
text: 'Security',
64-
items: [
65-
{ text: 'Json Web Token', link: '/guide/api-json-web-token' },
66-
{ text: 'Cross-Origin Resource Sharing', link: '/guide/api-cors' },
67-
{ text: 'SSL Certificate', link: '/guide/ssl-certificate' },
68-
]
69-
},
70-
{
71-
text: 'Communication',
72-
items: [
73-
{ text: 'Server Sent Events', link: '/guide/server-sent-events' },
74-
{ text: 'Websockets', link: '/guide/websockets' },
75-
]
76-
},
77-
{
78-
text: 'Others',
79-
items: [
80-
{ text: 'Static Files', link: '/guide/static-files' },
81-
{ text: 'Observability', link: '/guide/observability' },
82-
]
83-
},
84-
],
49+
{
50+
text: 'Introduction',
51+
items: [
52+
{ text: 'What is SimpleW?', link: '/guide/what-is-simplew' },
53+
{ text: 'Getting Started', link: '/guide/getting-started' },
54+
{ text: 'Performances', link: '/guide/performances' },
55+
//{ text: 'Lifecycle', link: '/guide/lifecycle' },
56+
]
57+
},
58+
{
59+
text: 'Serve API',
60+
items: [
61+
{ text: 'Basic', link: '/guide/api-basic' },
62+
{ text: 'Routing', link: '/guide/api-routing' },
63+
{ text: 'Response', link: '/guide/api-response' },
64+
{ text: 'Request', link: '/guide/api-request' },
65+
{ text: 'Callback', link: '/guide/api-callback' },
66+
]
67+
},
68+
{
69+
text: 'Security',
70+
items: [
71+
{ text: 'Json Web Token', link: '/guide/api-json-web-token' },
72+
{ text: 'Cross-Origin Resource Sharing', link: '/guide/api-cors' },
73+
{ text: 'SSL Certificate', link: '/guide/ssl-certificate' },
74+
]
75+
},
76+
{
77+
text: 'Communication',
78+
items: [
79+
{ text: 'Server Sent Events', link: '/guide/server-sent-events' },
80+
{ text: 'Websockets', link: '/guide/websockets' },
81+
]
82+
},
83+
{
84+
text: 'Others',
85+
items: [
86+
{ text: 'Static Files', link: '/guide/static-files' },
87+
{ text: 'Observability', link: '/guide/observability' },
88+
]
89+
},
90+
],
8591

92+
'/reference/': [
93+
{
94+
text: 'Reference',
95+
items: [
96+
{ text: 'Server', link: '/reference/simplewserver' },
97+
{ text: 'RouteAttribute', link: '/reference/routeattribute' },
98+
{
99+
text: 'Controller',
100+
base: '/reference/controller-',
101+
items: [
102+
{ text: 'Overview', link: 'overview' },
103+
{ text: 'HttpRequest', link: 'httprequest' },
104+
{ text: 'HttpResponse', link: 'httpresponse' },
105+
{ text: 'OnBeforeMethod', link: 'onbeforemethod' },
106+
]
107+
},
108+
{ text: 'NetCoreServerExtension', link: '/reference/netcoreserverextension' },
109+
]
110+
},
111+
]
86112

87113
},
88114

@@ -93,7 +119,7 @@ export default defineConfig({
93119

94120
footer: {
95121
message: 'Released under the MIT License.',
96-
copyright: 'Copyright © 2024-present StratDev'
122+
copyright: 'Copyright © 2021-present StratDev'
97123
},
98124

99125
search: {

documentation/docs/guide/api-basic.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# Basic
22

33
Few lines of code to setup a REST API :
4-
- `SimpleWServer` : main class to manage the server (Start, Stop, Add Components)
5-
- `Controller` : base class for your middleware to inherit Request/Response properties
4+
- [`SimpleWServer`](../reference/simplewserver) : main class to manage the server (Start, Stop, Add Components)
5+
- [`Controller`](../reference/controller-overview) : base class for your middleware to inherit Request/Response properties
66
- `Route` : attribut to target method of your middleware
77
- `Data` : data return by middleware is default serialized to json and sent as reponse
88

@@ -17,5 +17,5 @@ The following code is full of comments :
1717
Then just open your browser to http://localhost:2015/api/test and you will see the `{ "message": "Hello World !" }` json response.
1818

1919
::: tip NOTE
20-
The controller __CAN NOT__ have constructor. All properties `Request`, `Response` (...) will be set after session instanciation. See [callback](./api-callback) on how to inject specific code in all controllers of methods.
20+
The controller __CAN NOT__ have constructor. All properties [`Request`](../reference/controller-httprequest), [`Response`](../reference/controller-httpresponse) (...) will be injected after session instanciation. See [callback](./api-callback) on how to inject specific code in all controllers of methods.
2121
:::

documentation/docs/guide/api-callback.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ The behavior of SimpleW can be overridden using a sort of callback.
44

55
## OnBeforeMethod
66

7-
The `Controller` class contains an abstract method `OnBeforeMethod()` which is called before any method execution.
7+
The `Controller` class contains an abstract method [`OnBeforeMethod()`](../reference/controller-onbeforemethod) which is called before any method execution.
88

99
::: code-group
1010

documentation/docs/guide/api-json-web-token.md

Lines changed: 44 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -4,41 +4,54 @@
44
[JSON Web Tokens](https://jwt.io/) are an open, industry standard [RFC 7519](https://tools.ietf.org/html/rfc7519) method for representing claims securely between two parties.
55
SimpleW internal use the [LitJWT](https://github.com/Cysharp/LitJWT) project to forge and verify json web token.
66

7-
## Get Token
87

9-
The `Controller.GetJwt()` can be used to get the raw JWT string sent by a client.
8+
## Forge Token
109

11-
Backend receive
10+
The `NetCoreServerExtension.CreateJwt()` method can be used to forge a json token.
1211

1312
::: code-group
1413

15-
<<< @/snippets/jwt-get.cs#snippet{csharp:line-numbers} [program.cs]
14+
<<< @/snippets/jwt-forge.cs#snippet{31 csharp:line-numbers} [program.cs]
1615

1716
:::
1817

19-
Frontend send with JWT as a classic `Bearer Authorisation` Header
18+
Then just point your browser to http://localhost:2015/api/test/forge to get the token.
19+
20+
21+
## Retrieve Token
2022

21-
```bash
23+
Examples of a classic `Bearer Authorisation` Header sent by client
24+
25+
```sh
2226
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" \
2327
"http://localhost:2015/api/test/token"
2428
```
2529

26-
Frontend send with JWT as `jwt` query string
30+
Exemples of a Token sent by client as a `jwt` query string
2731

28-
```bash
29-
curl -H "Authorization: Bearer " \
30-
"http://localhost:2015/api/test/token?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
32+
```sh
33+
curl "http://localhost:2015/api/test/token?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
3134
```
3235

33-
### Notes
36+
The `Controller.GetJwt()` can be used to get the raw JWT string sent by a client.
37+
38+
::: code-group
39+
40+
<<< @/snippets/jwt-get.cs#snippet{22 csharp:line-numbers} [program.cs]
41+
42+
:::
43+
44+
::: tip NOTE
3445

3546
There is no need to declare specific parameter in the Controller.
47+
The `GetJwt()` will parse the client request looking for, by order of appearance :
3648

37-
The `GetJwt()` will internally parse the client request looking for, by order of appearance :
3849
1. `Session.jwt` (websocket only)
3950
2. `jwt` querystring in the request url (api only)
4051
3. `Authorization: bearer` in the request header (api only)
4152

53+
:::
54+
4255
### Why different ways for passing jwt ?
4356

4457
Passing jwt in the `Header` __should always__ be the preferred method.
@@ -47,6 +60,7 @@ But sometimes, header cannot be modified by client and passing jwt in the url is
4760

4861
In this case, try to forge a specific JWT with role based access limited to the target ressource only and a very short period expiration (see next chapter to [forge jwt](#forge-jwt)).
4962

63+
5064
### Override GetJwt()
5165

5266
You can provide your own implementation of the `GetJwt()` by overriding in a [subclass](#subclass).
@@ -62,61 +76,57 @@ Example of overriding
6276

6377
## Verify Token
6478

65-
The `ValidateJwt<T>()` string extension can be used to verify a json token.
66-
67-
Frontend with a jwt (forge with "secret" as secret, see [jwt.io](https://jwt.io) for details)
79+
Examples of a classic `Bearer Authorisation` Header sent by client. The token was forged with "secret" as secret (see [jwt.io](https://jwt.io) for details).
6880

69-
```bash
81+
```sh
7082
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiaWQiOiJiODRjMDM5Yy0zY2QyLTRlN2ItODEyYy05MTQxZWQ2YzU2ZTQiLCJuYW1lIjoiSm9obiBEb2UiLCJyb2xlcyI6WyJhY2NvdW50Il0sImlhdCI6MjUxNjIzOTAyMn0.QhJ1EiMIt4uAGmYrGAC53PxoHIfX6aiWiLRbhastoB4" \
7183
"http://localhost:2015/api/user/account"
7284
```
7385

74-
Backend receive
86+
The `ValidateJwt<T>()` string extension can be used to verify a json token.
7587

7688
::: code-group
7789

7890
<<< @/snippets/jwt-verify.cs#snippet{csharp:line-numbers} [program.cs]
7991

8092
:::
8193

82-
The `ValidateJwt<UserToken>()` will verify token and convert payload into a `UserToken` instance.
94+
::: tip NOT
95+
96+
The `ValidateJwt<UserToken>()` string extension will verify token and convert payload into a `UserToken` instance.
8397
Then, you can use `userToken` to check according to your business rules.
8498

99+
:::
85100

86101
### Refactor the JWT verification logic
87102

88-
This example shows how to integrate a global custom jwt verification in all controllers using [subclass](#subclass) and [hooks](#hooks)
103+
This example shows how to integrate a global custom jwt verification in all controllers using [callback](./api-callback).
104+
89105

90-
Frontend send
106+
Examples of a classic `Bearer Authorisation` Header sent by client.
91107

92-
```bash
108+
```sh
93109
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiaWQiOiJiODRjMDM5Yy0zY2QyLTRlN2ItODEyYy05MTQxZWQ2YzU2ZTQiLCJuYW1lIjoiSm9obiBEb2UiLCJyb2xlcyI6WyJhY2NvdW50Il0sImlhdCI6MjUxNjIzOTAyMn0.QhJ1EiMIt4uAGmYrGAC53PxoHIfX6aiWiLRbhastoB4" \
94110
"http://localhost:2015/api/user/account"
95111
```
96112

97-
Backend receive
113+
Backend
98114

99115
::: code-group
100116

101117
<<< @/snippets/jwt-verify-full.cs#snippet{csharp:line-numbers} [program.cs]
102118

103119
:::
104120

105-
## Forge Token
106-
107-
The `NetCoreServerExtension.CreateJwt()` method can be used to forge a json token which will be [Validate](#verify-jwt) later.
108-
121+
<!--
122+
## Setup Token
109123
110-
```bash
111-
curl "http://localhost:2015/api/test/forge"
112-
```
113-
114-
Backend receive
124+
Working with `CreateJwt()` or `ValidateJwt<T>` involves passing the secret as parameter each time.
125+
To avoid this, you can use the `SetToken()` to pass the secret once in the server instance.
115126
116127
::: code-group
117128
118-
<<< @/snippets/jwt-forge.cs#snippet{csharp:line-numbers} [program.cs]
129+
<<< @/snippets/jwt-setup.cs#snippet{13 csharp:line-numbers} [program.cs]
119130
120131
:::
121-
122-
Note: Just browse `NetCoreServerExtension.CreateJwt()` to discover all parameters.
132+
-->

documentation/docs/guide/api-request.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
# Request
22

3-
The `Request` property of `Controller` class contains all the information (Url, Headers, Method, Protocol, Body...) about the request sent by the client.
3+
The [`Request`](../reference/controller-httprequest) property of [`Controller`](../reference/controller-overview) class contains all the information (Url, Headers, Method, Protocol, Body...) about the request sent by the client.
44

55

66
## Body
77

8-
You can use the `Request.Body` property to retrieve the data from any `POST` request.
8+
You can use the [`Request.Body`](../reference/controller-httprequest#body) property to retrieve the data from any `POST` request.
99

1010
Frontend send POST data
1111

@@ -54,7 +54,7 @@ You sent data in the body
5454

5555
## Body (application/json) deserialization helper
5656

57-
You can use the `BodyMap()` helper method for reading `Request.Body` and deserialize to an object instance.
57+
You can use the [`BodyMap()`](../reference/controller-httprequest#bodymap) helper method for reading [`Request.Body`](../reference/controller-httprequest#body) and deserialize to an object instance.
5858

5959
Frontend send POST json data
6060

@@ -130,7 +130,7 @@ Note :
130130

131131
## Body (application/x-www-form-urlencoded) deserialization helper
132132

133-
You can use the `BodyMap()` method for reading `Request.Body` and deserialize to an object instance.
133+
You can use the [`BodyMap()`](../reference/controller-httprequest#bodymap) method for reading [`Request.Body`](../reference/controller-httprequest#body) and deserialize to an object instance.
134134

135135
Frontend send POST json data
136136

@@ -202,7 +202,7 @@ specification. That's why :
202202

203203
## Body (multipart/form-data) deserialization helper
204204

205-
You can use the `BodyFile()` method for reading `Request.Body` containing files.
205+
You can use the [`BodyFile()`](../reference/controller-httprequest#bodyfile) method for reading [`Request.Body`](../reference/controller-httprequest#body) containing files.
206206

207207
Frontend send a file POST
208208

documentation/docs/guide/api-response.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -140,10 +140,10 @@ Most of the time, `object` is enough and will be passed to a `JsonConvert.Serial
140140

141141
## Helpers
142142

143-
In fact, the `Controller` class is dealing with an `HttpResponse` object which is sent async to the client.<br />
143+
In fact, the `Controller` class is dealing with an [`HttpResponse`](../reference/controller-httpresponse) object which is sent async to the client.<br />
144144
You can manipulate this object with the property `Response`.
145145

146-
There are also some useful helpers that facilitate returning specific `HttpReponse` :
146+
There are also some useful [helpers](../reference/controller-httpresponse) to create common response :
147147

148148
```csharp:line-numbers
149149
using System;

documentation/docs/guide/api-routes.md renamed to documentation/docs/guide/api-routing.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22

33

44
Each URL is a concatenation of :
5-
1. `Prefix` defined by a Component (e.g: `AddDynamicContent()`, `AddStaticContent()`).
6-
2. `Route` attribute on Controller class (if exists).
7-
3. `Route` attribute on Method.
5+
1. `Prefix` defined by a Component (e.g: [`AddDynamicContent()`](../reference/simplewserver#adddynamiccontent), [`AddStaticContent()`](../reference/simplewserver#addstaticcontent)).
6+
2. [`Route`](../reference/routeattribute#controller) attribute on Controller class (if exists).
7+
3. [`Route`](../reference/routeattribute#method) attribute on Method.
88

99

1010
## The Route Attribut

0 commit comments

Comments
 (0)