@tsed/swagger 6.102.0 → 6.102.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/package.json +13 -13
  2. package/readme.md +72 -82
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tsed/swagger",
3
- "version": "6.102.0",
3
+ "version": "6.102.1",
4
4
  "description": "Swagger package for Ts.ED framework",
5
5
  "private": false,
6
6
  "source": "./src/index.ts",
@@ -25,20 +25,20 @@
25
25
  "tslib": "2.2.0"
26
26
  },
27
27
  "devDependencies": {
28
- "@tsed/common": "6.102.0",
29
- "@tsed/core": "6.102.0",
30
- "@tsed/di": "6.102.0",
31
- "@tsed/json-mapper": "6.102.0",
32
- "@tsed/openspec": "6.102.0",
33
- "@tsed/schema": "6.102.0"
28
+ "@tsed/common": "6.102.1",
29
+ "@tsed/core": "6.102.1",
30
+ "@tsed/di": "6.102.1",
31
+ "@tsed/json-mapper": "6.102.1",
32
+ "@tsed/openspec": "6.102.1",
33
+ "@tsed/schema": "6.102.1"
34
34
  },
35
35
  "peerDependencies": {
36
- "@tsed/common": "^6.102.0",
37
- "@tsed/core": "^6.102.0",
38
- "@tsed/di": "^6.102.0",
39
- "@tsed/json-mapper": "^6.102.0",
40
- "@tsed/openspec": "^6.102.0",
41
- "@tsed/schema": "^6.102.0"
36
+ "@tsed/common": "^6.102.1",
37
+ "@tsed/core": "^6.102.1",
38
+ "@tsed/di": "^6.102.1",
39
+ "@tsed/json-mapper": "^6.102.1",
40
+ "@tsed/openspec": "^6.102.1",
41
+ "@tsed/schema": "^6.102.1"
42
42
  },
43
43
  "repository": "https://github.com/tsedio/tsed",
44
44
  "bugs": {
package/readme.md CHANGED
@@ -43,25 +43,24 @@ Then add the following configuration in your Server:
43
43
  import {Configuration} from "@tsed/common";
44
44
  import "@tsed/swagger"; // import swagger Ts.ED module
45
45
  import {resolve} from "path";
46
- const rootDir = resolve(__dirname)
46
+ const rootDir = resolve(__dirname);
47
47
 
48
48
  @Configuration({
49
49
  rootDir,
50
50
  swagger: [
51
51
  {
52
- path: "/v2/docs",
53
- specVersion: "2.0"
52
+ path: "/v2/docs",
53
+ specVersion: "2.0"
54
54
  },
55
55
  {
56
- path: "/v3/docs",
57
- specVersion: "3.0.1"
56
+ path: "/v3/docs",
57
+ specVersion: "3.0.1"
58
58
  }
59
59
  ]
60
60
  })
61
- export class Server {
62
-
63
- }
61
+ export class Server {}
64
62
  ```
63
+
65
64
  > The path option for swagger will be used to expose the documentation (ex: http://localhost:8000/api-docs).
66
65
 
67
66
  Normally, Swagger-ui is ready. You can start your server and check if it work fine.
@@ -72,21 +71,21 @@ Normally, Swagger-ui is ready. You can start your server and check if it work fi
72
71
 
73
72
  Some options is available to configure Swagger-ui, Ts.ED and the default spec information.
74
73
 
75
- Key | Example | Description
76
- ---|---|---
77
- path | `/api-doc` | The url subpath to access to the documentation.
78
- specVersion | `2.0`, `3.0.1` | The spec version.
79
- doc | `hidden-doc` | The documentation key used by `@Docs` decorator to create several swagger documentations.
80
- cssPath | `${rootDir}/spec/style.css` | The path to the CSS file.
81
- jsPath | `${rootDir}/spec/main.js` | The path to the JS file.
82
- showExplorer | `true` | Display the search field in the navbar.
83
- spec | `{swagger: "2.0"}` | The default information spec.
84
- specPath | `${rootDir}/spec/swagger.base.json` | Load the base spec documentation from the specified path.
85
- outFile | `${rootDir}/spec/swagger.json` | Write the `swagger.json` spec documentation on the specified path.
86
- hidden | `true` | Hide the documentation in the dropdown explorer list.
87
- options | Swagger-UI options | SwaggerUI options. See (https://github.com/swagger-api/swagger-ui/blob/HEAD/docs/usage/configuration.md)
88
- operationIdFormatter | `(name: string, propertyKey: string, path: string) => string` | A function to generate the operationId.
89
- operationIdPattern | `%c_%m` | A pattern to generate the operationId. Format of operationId field (%c: class name, %m: method name).
74
+ | Key | Example | Description |
75
+ | -------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
76
+ | path | `/api-doc` | The url subpath to access to the documentation. |
77
+ | specVersion | `2.0`, `3.0.1` | The spec version. |
78
+ | doc | `hidden-doc` | The documentation key used by `@Docs` decorator to create several swagger documentations. |
79
+ | cssPath | `${rootDir}/spec/style.css` | The path to the CSS file. |
80
+ | jsPath | `${rootDir}/spec/main.js` | The path to the JS file. |
81
+ | showExplorer | `true` | Display the search field in the navbar. |
82
+ | spec | `{swagger: "2.0"}` | The default information spec. |
83
+ | specPath | `${rootDir}/spec/swagger.base.json` | Load the base spec documentation from the specified path. |
84
+ | outFile | `${rootDir}/spec/swagger.json` | Write the `swagger.json` spec documentation on the specified path. |
85
+ | hidden | `true` | Hide the documentation in the dropdown explorer list. |
86
+ | options | Swagger-UI options | SwaggerUI options. See (https://github.com/swagger-api/swagger-ui/blob/HEAD/docs/usage/configuration.md) |
87
+ | operationIdFormatter | `(name: string, propertyKey: string, path: string) => string` | A function to generate the operationId. |
88
+ | operationIdPattern | `%c_%m` | A pattern to generate the operationId. Format of operationId field (%c: class name, %m: method name). |
90
89
 
91
90
  ### Multi documentations
92
91
 
@@ -101,17 +100,15 @@ import "@tsed/swagger"; // import swagger Ts.ED module
101
100
  swagger: [
102
101
  {
103
102
  path: "/api-docs-v1",
104
- doc: 'api-v1'
103
+ doc: "api-v1"
105
104
  },
106
105
  {
107
106
  path: "/api-docs-v2",
108
- doc: 'api-v2'
107
+ doc: "api-v2"
109
108
  }
110
109
  ]
111
110
  })
112
- export class Server {
113
-
114
- }
111
+ export class Server {}
115
112
  ```
116
113
 
117
114
  Then use `@Docs` decorators on your controllers to specify where the controllers should be displayed.
@@ -120,19 +117,17 @@ Then use `@Docs` decorators on your controllers to specify where the controllers
120
117
  import {Controller} from "@tsed/common";
121
118
  import {Docs} from "@tsed/swagger";
122
119
 
123
- @Controller('/calendars')
124
- @Docs('api-v2') // display this controllers only for api-docs-v2
125
- export class CalendarCtrlV2 {
126
- }
127
- // OR
128
- @Controller('/calendars')
129
- @Docs('api-v2', 'api-v1') // display this controllers for api-docs-v2 and api-docs-v1
130
- export class CalendarCtrl {
131
-
132
- }
133
- ```
120
+ @Controller("/calendars")
121
+ @Docs("api-v2") // display this controllers only for api-docs-v2
122
+ export class CalendarCtrlV2 {}
123
+ // OR
124
+ @Controller("/calendars")
125
+ @Docs("api-v2", "api-v1") // display this controllers for api-docs-v2 and api-docs-v1
126
+ export class CalendarCtrl {}
127
+ ```
134
128
 
135
129
  ## Examples
130
+
136
131
  #### Model documentation
137
132
 
138
133
  One of the feature of Ts.ED is the model definition to serialize or deserialize a
@@ -162,50 +157,49 @@ import {BodyParams, Controller, Get, Post, QueryParams, Returns, ReturnsArray, D
162
157
  import {Summary, Deprecated, Security} from "@tsed/swagger";
163
158
  import {CalendarModel} from "../models/CalendarModel";
164
159
 
165
- @Controller('/calendars')
160
+ @Controller("/calendars")
166
161
  export class Calendar {
167
- @Get('/:id')
168
- @Summary("Summary of this route")
169
- @Description("Description of this route")
170
- @Returns(CalendarModel)
171
- @Returns(404, {description: "Not found"})
172
- async getCalendar(@QueryParams('id') id: string): Promise<CalendarModel> {
173
- //...
174
- }
175
-
176
- @Get('/v0/:id')
177
- @Deprecated()
178
- @Description("Deprecated route, use /rest/calendars/:id instead of.")
179
- @Returns(CalendarModel)
180
- @Returns(404, {description: "Not found"})
181
- getCalendarDeprecated(@QueryParams('id') id: string): Promise<CalendarModel> {
182
- //...
183
- }
184
-
185
- @Get('/')
186
- @Description("Description of this route")
187
- @ReturnsArray(CalendarModel)
188
- getCalendars(): Promise<CalendarModel[]> {
189
- // ...
190
- }
191
-
192
- @Post('/')
193
- @Security("calendar_auth", "write:calendar", "read:calendar")
194
- @Returns(CalendarModel)
195
- async createCalendar(@BodyParams() body: any): Promise<CalendarModel> {
196
- //...
197
- }
162
+ @Get("/:id")
163
+ @Summary("Summary of this route")
164
+ @Description("Description of this route")
165
+ @Returns(CalendarModel)
166
+ @Returns(404, {description: "Not found"})
167
+ async getCalendar(@QueryParams("id") id: string): Promise<CalendarModel> {
168
+ //...
169
+ }
170
+
171
+ @Get("/v0/:id")
172
+ @Deprecated()
173
+ @Description("Deprecated route, use /rest/calendars/:id instead of.")
174
+ @Returns(CalendarModel)
175
+ @Returns(404, {description: "Not found"})
176
+ getCalendarDeprecated(@QueryParams("id") id: string): Promise<CalendarModel> {
177
+ //...
178
+ }
179
+
180
+ @Get("/")
181
+ @Description("Description of this route")
182
+ @ReturnsArray(CalendarModel)
183
+ getCalendars(): Promise<CalendarModel[]> {
184
+ // ...
185
+ }
186
+
187
+ @Post("/")
188
+ @Security("calendar_auth", "write:calendar", "read:calendar")
189
+ @Returns(CalendarModel)
190
+ async createCalendar(@BodyParams() body: any): Promise<CalendarModel> {
191
+ //...
192
+ }
198
193
  }
199
194
  ```
195
+
200
196
  ::: warninig
201
197
  To update the swagger.json you need to reload the server before.
202
198
  :::
203
199
 
204
-
205
200
  ## Import Javascript
206
201
 
207
- It possible to import a Javascript in the Swagger-ui documentation. This script let you customize the swagger-ui instance.
208
-
202
+ It possible to import a Javascript in the Swagger-ui documentation. This script let you customize the swagger-ui instance.
209
203
 
210
204
  ```typescript
211
205
  import {Configuration} from "@tsed/common";
@@ -220,9 +214,7 @@ import "@tsed/swagger"; // import swagger Ts.ED module
220
214
  }
221
215
  ]
222
216
  })
223
- export class Server {
224
-
225
- }
217
+ export class Server {}
226
218
  ```
227
219
 
228
220
  In your JavaScript file, you can handle Swagger-ui configuration and the instance:
@@ -230,8 +222,8 @@ In your JavaScript file, you can handle Swagger-ui configuration and the instanc
230
222
  ```javascript
231
223
  console.log(SwaggerUIBuilder.config); //Swagger-ui config
232
224
 
233
- document.addEventListener('swagger.init', (evt) => {
234
- console.log(SwaggerUIBuilder.ui); //Swagger-ui instance
225
+ document.addEventListener("swagger.init", (evt) => {
226
+ console.log(SwaggerUIBuilder.ui); //Swagger-ui instance
235
227
  });
236
228
  ```
237
229
 
@@ -239,20 +231,18 @@ document.addEventListener('swagger.init', (evt) => {
239
231
 
240
232
  See our documentation https://tsed.io/#/api/index
241
233
 
242
-
243
234
  ## Contributors
235
+
244
236
  Please read [contributing guidelines here](https://tsed.io/CONTRIBUTING.html).
245
237
 
246
238
  <a href="https://github.com/tsedio/ts-express-decorators/graphs/contributors"><img src="https://opencollective.com/tsed/contributors.svg?width=890" /></a>
247
239
 
248
-
249
240
  ## Backers
250
241
 
251
242
  Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/tsed#backer)]
252
243
 
253
244
  <a href="https://opencollective.com/tsed#backers" target="_blank"><img src="https://opencollective.com/tsed/tiers/backer.svg?width=890"></a>
254
245
 
255
-
256
246
  ## Sponsors
257
247
 
258
248
  Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/tsed#sponsor)]