@decorators/express-openapi

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	optional Default: {}	Options to configure swagger ui and the openapi document itself
options.serveInPath	string	optional Default: /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	optional Default: package name taken from your package.json
options.info.description	string	optional Default: package description taken from your package.json
options.info.version	string	optional Default: 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	optional Default: 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