Node decorators - express-openapi

openapi decorators and swagger-ui implementation extending @decorators/express

Installation

npm install @decorators/express-openapi

API

Functions

enableOpenApi(app: express.Application, options: OpenApiOptions = {}): Promise<void>

Initiates the openapi document and attaches it to the application.

Params::

| Name | Type | Attribute | Description | | ---- |----- | --------- | ----------- | | app | express.Application | | The application object | | options | object | optionalDefault: {} | Options to configure swagger ui and the openapi document itself | | options.serveInPath | string | optionalDefault: /api-docs | The url where the swagger-ui will be served | | options.info | object | optional | An object that represents the info on the openapi document. For more info see https://swagger.io/docs/specification/basic-structure/ | | options.info.title | string | optionalDefault: package name taken from your package.json | | | options.info.description | string | optionalDefault: package description taken from your package.json | | | options.info.version | string | optionalDefault: package version taken from your package.json | | | options.tags | object[] | optional | List of tags following the openapi specifications | | options.tags.[].name | string | | The tag name. | | options.tags.[].description | string | optional | The tag description | | options.servers | object[] | optional | List of servers following the openapi specifications. See https://swagger.io/docs/specification/api-host-and-base-path/ | | options.servers[].url | string | | | | options.servers[].description | string | optional | | | options.externalDocs | object | optional | External documents definition following the openapi specifications. | | options.externalDocs.url | string | | | | options.externalDocs.description | string | optional | | | options.security | object[] | optional | Security schemes to be applied to the api | | options.components.securitySchemes | object | optional | An object that represents the components.securitySchemes on the openapi document. For more info see https://swagger.io/docs/specification/authentication/ |

registerSchema(name: string, schema: SchemaDef): Promise<void>

Defines a schema on the openapi document

Params:

| Name | Type | Attribute | Description | | ---- |----- | --------- | ----------- | | name | string | | The name of the schema in the openapi document | | schema | object | | A schema object following openapi specifications. See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schemaObject |

Decorators

Class Decorators

@WithDefinitions(options: WithDefinitionsOpts)

Enables openapi definitions for a controller class (using @Controller() from @decorators/express)

Params:

| Name | Type | Attribute | Description | | ---- |----- | --------- | ----------- | | options | object | | | | options.tags | string[] | optional | Tags to be applied to all routes on the controller | | options.security | object[] | optional | Security schemes to be applied to all routes on the controller | | options.responses | object | optional | Tags to be applied to all routes on the controller | | options.basePath | string | | The base path for all routes on the controller |

@Schema(name?: string)

Defines a new schema on the openapi document. Internally uses registerSchema.

Params:

| Name | Type | Attribute | Description | | ---- |----- | --------- | ----------- | | name | string | optionalDefault: The class name | The name of the schema |

Method Decorators - Route documentation

@Summary(summary: string)

Defines the summary of the operation

Params:

| Name | Type | Attribute | Description | | ---- |----- | --------- | ----------- | | summary | string | | The operation's summary |

@Description(description: string)

Defines the description of the operation

Params:

| Name | Type | Attribute | Description | | ---- |----- | --------- | ----------- | | description | string | | The operation's description |

@Param(name: string, location: ParamLocation, schema: SchemaDef, options: ParamOptions)

Adds a param definition to the operation

Params:

| Name | Type | Attribute | Description | | ---- |----- | --------- | ----------- | | name | string | | The parameter name | | location | string | oneOf: query, header, path or cookie | Where the parameter is located | | schema | object | | A schema definition following openapi specifications | | options | object | optional | Options for the parameter following openapi specifications | | options.description | string | optional | | | options.required | boolean | optional | | | options.deprecated | boolean | optional | | | options.allowEmptyValue | boolean | optional | | | options.contentMediaType | string | optional | Media type definition complying with RFC 6838. If present, schema is rendered under content |

Note:

When using @Query(), @Params(), @Headers() or @Cookies() from @decorators/express defining the name attribute, a basic parameter definition is automatically added to the openapi document. This definition is equivalent to calling @Param(name, location) without passing options.

If you need to define extra options, a new call of @Param(name, location, options) will override the automatic definition.

Examples:

class Constructor {
  @Get('/:id')
  public getById(@Param('id') id, @Response() res) {
      // ...
  }
}

produces

...
"parameters": [
  { "name": "id", "in": "path", "required": true }
]
...

class Constructor {
  @Get('/:id')
  @Param('id', 'path', { required: true })
  public getById(@Request() req, @Response() res) {
      const id = req.params.id;
      // ...
  }
}

also produces

...
"parameters": [
  { "name": "id", "in": "path", "required": true }
]
...

@Tags(tag: string, ...tags: string[])

Defines one or more tags for the operation. If no tags are defined on method nor class level, then the class name will be used as default tag

Params:

| Name | Type | Attribute | Description | | ---- |----- | --------- | ----------- | | tag | string | | | | tags | string[] | optional | |

@Deprecated()

Marks an operation as deprecated on the openapi document

@BodyContent(mediaType: string, schema: SchemaDef)

Marks an operation as deprecated on the openapi document

Params:

| Name | Type | Attribute | Description | | ---- |----- | --------- | ----------- | | mediaTye | string | | Media type definition complying with RFC 6838 | | schema | object | | A schema definition following openapi specifications |

@Responses(def: { [key: string]: ResponseDescriptor })

Defines one or more responses for the operation

Params:

| Name | Type | Attribute | Description | | ---- |----- | --------- | ----------- | | def | object | | A map of responses following openapi specifications. See https://swagger.io/docs/specification/describing-responses/ | | def[] | object | | | | def[].description | string | | The description for the response | | def[*].content | object | |

@OpenApiResponse(status: string | number, description: string)

Defines the description for a response

Params:

| Name | Type | Attribute | Description | | ---- |----- | --------- | ----------- | | status | string \| number | | The response status | | description | string | | The description |

@OpenApiResponse(status: string | number, produces: string, schema: SchemaDef)

Defines one response schema for the operation

Params:

| Name | Type | Attribute | Description | | ---- |----- | --------- | ----------- | | status | string \| number | | The response status | | produces | string | | The media type described | | schema | object | | A schema definition following the openapi specifications |

@Security(schemeName: string, scopes?: string[])

Applies a security scheme to the operation

Params:

| Name | Type | Attribute | Description | | ---- | ---- | --------- | ----------- | | schemeName | string | | The scheme name | | scopes | string[] | optional | list of required scopes |

Property Decorators - Schema property

@Property(opts: SchemaDef & { required?: boolean })

Declares a property on a class using @Schema() decorator

Params:

| Name | Type | Attribute | Description | | ---- |----- | --------- | ----------- | | opts | object | | A property definition following the openapi specifications |