@decorators/express-openapi v2.1.0

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::

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

Defines a schema on the openapi document

Params:

Decorators

Class Decorators

@WithDefinitions(options: WithDefinitionsOpts)

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

Params:

@Schema(name?: string)

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

Params:

Method Decorators - Route documentation

@Summary(summary: string)

Defines the summary of the operation

Params:

@Description(description: string)

Defines the description of the operation

Params:

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

Adds a param definition to the operation

Params:

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:

@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:

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

Defines one or more responses for the operation

Params:

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

Defines the description for a response

Params:

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

Defines one response schema for the operation

Params:

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

Applies a security scheme to the operation

Params:

Property Decorators - Schema property

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

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

Params: