Docs update swagger page

docs/.vuepress/config.js

@@ -257,7 +257,6 @@ module.exports = {
           "/tutorials/throw-http-exceptions",
           "/tutorials/not-found-page",
           "/tutorials/aws",
-          "/tutorials/jest",
           "/tutorials/seq",
           "/docs/controllers",
           "/docs/providers",

docs/contributing.md

@@ -1,6 +1,6 @@
 ---
 layout: contributing
-pageClass: contributingpage
+pageClass: contributing page
 heroText: TS.ED
 heroVersion: community
 heroDescription: Become contributors

docs/docs/configuration.md

@@ -126,12 +126,11 @@ Port number for the [HTTPs.Server](https://nodejs.org/api/https.html#https_class
 
 ### httpsOptions
 
-- type: [Https.ServerOptions](https://nodejs.org/api/tls.html#tls_tls_createserver_options_secureconnectionlistener))
-
-* `key` <string> | <string[]> | [<Buffer>](https://nodejs.org/api/buffer.html#buffer_class_buffer) | <Object[]>: The private key of the server in PEM format. To support multiple keys using different algorithms, an array can be provided either as a plain array of key strings or an array of objects in the format `{pem: key, passphrase: passphrase}`. This option is required for ciphers making use of private keys.
-* `passphrase` <string> A string containing the passphrase for the private key or pfx.
-* `cert` <string> | <string[]> | [<Buffer>](https://nodejs.org/api/buffer.html#buffer_class_buffer) | [<Buffer[]>](https://nodejs.org/api/buffer.html#buffer_class_buffer): A string, Buffer, array of strings, or array of Buffers containing the certificate key of the server in PEM format. (Required)
-* `ca` <string> | <string[]> | [<Buffer>](https://nodejs.org/api/buffer.html#buffer_class_buffer) | [<Buffer[]>](https://nodejs.org/api/buffer.html#buffer_class_buffer): A string, Buffer, array of strings, or array of Buffers of trusted certificates in PEM format. If this is omitted, several well known "root" CAs (like VeriSign) will be used. These are used to authorize connections.
+- type: [Https.ServerOptions](https://nodejs.org/api/tls.html#tls_tls_createserver_options_secureconnectionlistener)
+  * `key` <string> | <string[]> | [<Buffer>](https://nodejs.org/api/buffer.html#buffer_class_buffer) | <Object[]>: The private key of the server in PEM format. To support multiple keys using different algorithms, an array can be provided either as a plain array of key strings or an array of objects in the format `{pem: key, passphrase: passphrase}`. This option is required for ciphers making use of private keys.
+  * `passphrase` <string> A string containing the passphrase for the private key or pfx.
+  * `cert` <string> | <string[]> | [<Buffer>](https://nodejs.org/api/buffer.html#buffer_class_buffer) | [<Buffer[]>](https://nodejs.org/api/buffer.html#buffer_class_buffer): A string, Buffer, array of strings, or array of Buffers containing the certificate key of the server in PEM format. (Required)
+  * `ca` <string> | <string[]> | [<Buffer>](https://nodejs.org/api/buffer.html#buffer_class_buffer) | [<Buffer[]>](https://nodejs.org/api/buffer.html#buffer_class_buffer): A string, Buffer, array of strings, or array of Buffers of trusted certificates in PEM format. If this is omitted, several well known "root" CAs (like VeriSign) will be used. These are used to authorize connections.
 
 See the [HTTPs project example](https://github.com/TypedProject/example-ts-express-decorator/tree/2.0.0/example-https)
 

docs/getting-started/migration-from-v5.md

@@ -45,7 +45,8 @@ New features are available:
 
 - Managing models using Typescript generics.
 - Management response models by content-type and status code (OAS3).
-- Configure swagger to generate OpenSpec3.
+- Add validation decorator on endpoint parameters.
+- [Configure swagger to generate OpenSpec3](/tutorials/swagger.md).
 
 :::
 

docs/snippets/getting-started/server.ts

@@ -1,5 +1,4 @@
 import {Configuration, Inject, PlatformApplication} from "@tsed/common";
-import {GlobalAcceptMimesMiddleware} from "@tsed/platform-express";
 import * as bodyParser from "body-parser";
 import * as compress from "compression";
 import * as cookieParser from "cookie-parser";
@@ -24,7 +23,6 @@ export class Server {
    */
   public $beforeRoutesInit(): void | Promise<any> {
     this.app
-      .use(GlobalAcceptMimesMiddleware) // optional
       .use(cookieParser())
       .use(compress({}))
       .use(methodOverride())

docs/tutorials/snippets/swagger/configuration.ts

@@ -6,7 +6,12 @@ import "@tsed/swagger"; // import swagger Ts.ED module
   rootDir: __dirname,
   swagger: [
     {
-      path: "/api-docs"
+      path: "/v2/docs",
+      specVersion: "2.0.0" // by default
+    },
+    {
+      path: "/v3/docs",
+      specVersion: "3.0.1"
     }
   ]
 })

docs/tutorials/snippets/swagger/endpoint-documentation.ts

@@ -1,22 +1,24 @@
-import {Description, BodyParams, Controller, Get, Post, QueryParams, Returns, ReturnsArray} from "@tsed/common";
-import {Deprecated, Security, Summary} from "@tsed/swagger";
+import {BodyParams, Controller, Get, Post, QueryParams} from "@tsed/common";
+import {Deprecated, Description, Returns, Security, Summary} from "@tsed/schema";
 import {CalendarModel} from "./models/Calendar";
 
 @Controller("/calendars")
-export class Calendar {
+export class CalendarCtrl {
   @Get("/:id")
   @Summary("Summary of this route")
   @Description("Return a calendar from the given id")
-  @Returns(CalendarModel)
-  @Returns(404, {description: "Not found"})
-  async getCalendar(@Description("A calendar Id") @QueryParams() id: string): Promise<CalendarModel> {
+  @Returns(200, CalendarModel)
+  @Returns(404).Description("Not found")
+  async getCalendar(
+    @Description("A calendar Id")
+    @QueryParams() id: string): Promise<CalendarModel> {
     return {};
   }
 
   @Get("/")
   @Description("Return a list of Calendar")
-  @ReturnsArray(CalendarModel)
-  getCalendars(): Promise<CalendarModel[]> {
+  @Returns(200, CalendarModel)
+  async getCalendars(): Promise<CalendarModel[]> {
     return [];
   }
 
@@ -25,7 +27,7 @@ export class Calendar {
   @Description("Deprecated route, use /rest/calendars/:id instead of.")
   @Returns(CalendarModel)
   @Returns(404, {description: "Not found"})
-  getCalendarDeprecated(@QueryParams("id") id: string): Promise<CalendarModel> {
+  async getCalendarDeprecated(@QueryParams("id") id: string): Promise<CalendarModel> {
     return {};
   }
 

docs/tutorials/snippets/swagger/endpoint-extra-in-params.ts

@@ -0,0 +1,13 @@
+import {BodyParams, Controller, Post} from "@tsed/common";
+import {In, Security} from "@tsed/schema";
+import {CalendarModel} from "./models/Calendar";
+
+@Controller("/calendars")
+export class CalendarCtrl {
+  @Post("/")
+  @In("authorization").Type(String).Description("Bearer authorization")
+  @Security("oidc")
+  async createCalendar(@BodyParams() body: any): Promise<CalendarModel> {
+    return {};
+  }
+}

docs/tutorials/swagger.md

@@ -7,9 +7,10 @@ meta:
 ---
 # Swagger
 
-<Banner src="https://swagger.io/swagger/media/assets/images/swagger_logo.svg" href="https://swagger.io/" :height="128" />
+<Banner src="https://swagger.io/swagger/media/assets/images/swagger_logo.svg" href="https://swagger.io/" :height="100" />
 
-This tutorial shows you how you can configure Swagger-ui with Ts.ED. Swagger uses the OpenApi
+
+This page shows you how you can configure Swagger-ui with Ts.ED. Swagger uses the OpenApi
 to describe a Rest API. Ts.ED operates the existing decorators as well as new decorators to build
 a spec compliant with Swagger.
 
@@ -18,18 +19,36 @@ a spec compliant with Swagger.
 Run this command to install required dependencies by `@tsed/swagger`:
 
 ```bash
-npm install --save @types/swagger-schema-official @tsed/swagger
+npm install --save @tsed/swagger
 ```
 
 Then add the following configuration in your Server:
 
+<Tabs class="-code">
+  <Tab label="Configuration">
+
 <<< @/docs/tutorials/snippets/swagger/configuration.ts
 
-> The path option for Swagger will be used to expose the documentation (ex: http://localhost:8000/api-docs).
+  </Tab>
+  <Tab label="CodeSandbox">
+
+<iframe src="https://codesandbox.io/embed/laughing-kepler-ripfl?fontsize=14&hidenavigation=1&theme=dark"
+     style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
+     title="tsed-swagger-example"
+     allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
+     sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"></iframe>
+
+  </Tab>
+</Tabs>  
+
+::: tip
+The path option for Swagger will be used to expose the documentation:
 
-Normally, Swagger-ui is ready. You can start your server and check if it works fine.
+- OAS2: [http://localhost:8000/v2/doc](http://localhost:8000/v2/doc)
+- OAS3: [http://localhost:8000/v3/doc](http://localhost:8000/v3/doc)
 
-> Note: Ts.ED will print the swagger url in the console.
+Ts.ED will print the swagger-ui url in the console.
+:::
 
 ### Swagger options
 
@@ -38,6 +57,7 @@ Some options are available to configure Swagger-ui, Ts.ED and the default spec i
 Key | Example | Description
 ---|---|---
 path | `/api-doc` |  The url subpath to access to the documentation.
+specVersion | `2.0`, `3.0.1`  |  The OpenSpec version.
 fileName | `swagger.json` | Swagger file name. By default swagger.json.
 doc | `hidden-doc` |  The documentation key used by `@Docs` decorator to create several swagger documentations.
 viewPath | `${rootDir}/../views/swagger.ejs` or `false` | The path to the ejs template. Set false to disabled swagger-ui.
@@ -50,7 +70,6 @@ specPath | `${rootDir}/spec/swagger.base.json` | Load the base spec documentatio
 outFile | `${rootDir}/spec/swagger.json` | Write the `swagger.json` spec documentation on the specified path.
 hidden | `true` | Hide the documentation in the dropdown explorer list.
 options | Swagger-UI options | SwaggerUI options. See (https://github.com/swagger-api/swagger-ui/blob/HEAD/docs/usage/docs/configuration.md)
-operationIdFormat | `%c.%m` | Format of operationId field (`%c`: class name, `%m`: method name).
 
 ### Multi documentations
 
@@ -62,37 +81,27 @@ Then use `@Docs` decorators on your controllers to specify where the controllers
 
 <<< @/docs/tutorials/snippets/swagger/multi-spec-controllers.ts
 
-## Decorators
-
-These decorators already add a documentation on Swagger:
-
-<ApiList query="['Header', 'Status'].indexOf(symbolName) > -1 || status.indexOf('jsonschema') > -1" />
-
-In addition, the Ts.ED Swagger plugin gives some decorators to write documentation:
-
-<ApiList query="module === '@tsed/swagger' && symbolType === 'decorator'" />
-
-## Examples
-#### Model documentation
+## Model documentation
 
 One of the feature of Ts.ED is the model definition to serialize or deserialize a
-JSON Object (see [converters section](/docs/converters.md)).
+JSON Object based on JsonSchema (See [model documentation](/docs/model.md)).
 
-This model can be used on a method controller along with [@BodyParams](/api/common/filters/decorators/BodyParams.md) or other decorators.
+A model can be used on a method controller along with [@BodyParams](/api/common/filters/decorators/BodyParams.md) or other decorators.
 
 <<< @/docs/tutorials/snippets/swagger/model.ts
 
-#### Endpoint documentation
+## Endpoint documentation
+
+This example shows you how to use the decorators to generate swagger documentation for an endpoint:
 
 <<< @/docs/tutorials/snippets/swagger/endpoint-documentation.ts
 
-::: tip
-For endpoints returning an array you have to use the @@ReturnsArray@@ decorator instead of @@Returns@@
-:::
+## Extra parameters
 
-::: warning
-To update the `swagger.json` you have to reload the server before.
-:::
+Sometimes you want to display extra `in` parameters like `headers` without consuming it in an endpoint.
+It's possible describe extra parameters by using the @@In@@ decorator over the method.
+
+<<< @/docs/tutorials/snippets/swagger/endpoint-extra-in-params.ts
 
 ## Import Javascript
 
@@ -110,9 +119,20 @@ document.addEventListener('swagger.init', (evt) => {
 });
 ```
 
-## Author 
+## Decorators
+
+These decorators already add a documentation on Swagger:
+
+<ApiList query="['Header', 'Status'].indexOf(symbolName) > -1 || (status.includes('decorator') && status.includes('schema'))" />
+
+In addition, the Ts.ED Swagger plugin gives some decorators to manage documentation:
+
+<ApiList query="module === '@tsed/swagger' && symbolType === 'decorator'" />
+
+
+## Authors
 
-<GithubContributors users="['vologab']"/>
+<GithubContributors users="['vologab', 'Romakita']"/>
 
 ## Maintainers
 

lerna.json

@@ -4,7 +4,7 @@
   "packages": [
     "packages/*"
   ],
-  "version": "6.0.0-beta.13",
+  "version": "6.0.0-beta.14",
   "command": {
     "bootstrap": {
       "npmClientArgs": [

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tsed/root",
-  "version": "6.0.0-beta.13",
+  "version": "6.0.0-beta.14",
   "description": "A TypeScript Framework on top of Express",
   "private": true,
   "scripts": {
@@ -79,7 +79,7 @@
     "consolidate": "0.16.0"
   },
   "devDependencies": {
-    "@tsed/monorepo-utils": "1.9.5",
+    "@tsed/monorepo-utils": "1.10.0",
     "@typedproject/ts-doc": "4.0.9",
     "@types/chai": "4.2.12",
     "@types/chai-as-promised": "7.1.3",

packages/ajv/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tsed/ajv",
-  "version": "6.0.0-beta.13",
+  "version": "6.0.0-beta.14",
   "description": "AJV package for Ts.ED framework",
   "main": "./lib/index.js",
   "typings": "./lib/index.d.ts",
@@ -16,8 +16,8 @@
   },
   "private": false,
   "devDependencies": {
-    "@tsed/common": "6.0.0-beta.13",
-    "@tsed/core": "6.0.0-beta.13",
+    "@tsed/common": "6.0.0-beta.14",
+    "@tsed/core": "6.0.0-beta.14",
     "ajv": "6.12.4"
   }
 }

packages/common/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tsed/common",
-  "version": "6.0.0-beta.13",
+  "version": "6.0.0-beta.14",
   "description": "A TypeScript Framework on top of Express",
   "main": "./lib/index.js",
   "typings": "./lib/index.d.ts",
@@ -45,12 +45,12 @@
     "build": "tsc --build tsconfig.compile.json"
   },
   "dependencies": {
-    "@tsed/core": "6.0.0-beta.13",
-    "@tsed/di": "6.0.0-beta.13",
-    "@tsed/exceptions": "6.0.0-beta.13",
-    "@tsed/json-mapper": "6.0.0-beta.13",
+    "@tsed/core": "6.0.0-beta.14",
+    "@tsed/di": "6.0.0-beta.14",
+    "@tsed/exceptions": "6.0.0-beta.14",
+    "@tsed/json-mapper": "6.0.0-beta.14",
     "@tsed/logger": "5.5.3",
-    "@tsed/schema": "6.0.0-beta.13",
+    "@tsed/schema": "6.0.0-beta.14",
     "@types/json-schema": "7.0.6",
     "consolidate": "^0.16.0",
     "ejs": "^3.1.5",

packages/common/src/mvc/decorators/method/contentType.ts

@@ -19,6 +19,7 @@ import {Returns} from "@tsed/schema";
  * @response
  * @headers
  * @deprecated Since v6. Use @Returns().ContentType() instead.
+ * @ignore
  */
 export function ContentType(type: string) {
   return Returns().ContentType(type);

packages/common/src/mvc/decorators/method/returnType.ts

@@ -3,13 +3,15 @@ import {Returns as R, ReturnsChainedDecorators} from "@tsed/schema";
 
 /**
  * @deprecated Since v6.
+ * @ignore
  */
 export interface ReturnTypeHeader {
   value?: string | number;
 }
 
 /**
  * @deprecated Since v6.
+ * @ignore
  */
 export interface ReturnTypeOptions extends Partial<MetadataTypes> {
   code?: number;

packages/common/src/mvc/decorators/required.ts

@@ -45,6 +45,7 @@ import {Allow} from "@tsed/schema";
  * @schema
  * @validation
  * @deprecated Since v6. Use @Allow decorator from @tsed/schema instead of.
+ * @ignore
  */
 export function Required(...allowedRequiredValues: any[]): any {
   return Allow(...allowedRequiredValues);

packages/common/src/mvc/interfaces/HandlerType.ts

@@ -1,3 +1,6 @@
+/**
+ * @ignore
+ */
 export enum HandlerType {
   CUSTOM = "custom",
   ENDPOINT = "endpoint",

packages/common/src/mvc/interfaces/IInjectableParamSettings.ts

@@ -2,7 +2,7 @@ import {Type} from "@tsed/core";
 import {IParamOptions} from "./IParamOptions";
 
 /**
- *
+ * @ignore
  */
 export interface IInjectableParamSettings<T> extends IParamOptions<T> {
   target: Type<T>;