OpenAPI is a language-agnostic specification for declaring API documentation for REST APIs. NestJS offers a Swagger plugin for producing the API docs.
Setup
Configure API documentation with the required endpoint, like /api-docs.
const SWAGGER_API_ENDPOINT = '/api-docs';
// ...
export const setupApiDocs = (app: INestApplication): void => {
const choices = new DocumentBuilder()
.setTitle(SWAGGER_API_TITLE)
.setDescription(SWAGGER_API_DESCRIPTION)
.setVersion(SWAGGER_API_VERSION)
.addSecurity('token', {
kind: 'apiKey',
scheme: 'api_key',
in: 'header',
title: 'auth-token',
})
.addBearerAuth()
.construct();
const doc = SwaggerModule.createDocument(app, choices);
SwaggerModule.setup(SWAGGER_API_ENDPOINT, app, doc);
};
Configure the plugin within the NestJS config file.
{
"compilerOptions": {
"plugins": ["@nestjs/swagger"]
}
}
JSON and YAML codecs are generated at /api-docs-json and /api-docs-yaml endpoints, respectively.
Decorators
@ApiTags('customers')
@Controller('customers')
export class UsersController {
// ...
}
-
ApiOperationoffers extra particulars like a abstract and outline of the endpoint
@ApiOperation({
abstract: 'Get consumer',
description: 'Get consumer by id',
})
@Get(':id')
async getById(
@Param('id', new ParseUUIDPipe()) id: string,
): Promise<UserDto> {
// ...
}
-
@ApiPropertyand@ApiPropertyOptionalmust be used for request and response DTOs fields. Instance and outline values will probably be proven within the generated documentation.
export class CreateUserDto {
@ApiProperty({ instance: 'John', description: 'first title of the consumer' })
// ...
public firstName: string;
@ApiPropertyOptional({ instance: 'Doe', description: 'final title of the consumer' })
// ...
public lastName?: string;
}
-
ApiHeaderpaperwork endpoint headers
@ApiHeader({
title: 'correlation-id',
required: false,
description: 'distinctive id for correlated logs',
instance: '7ea2c7f7-8b46-475d-86f8-7aaaa9e4a35b',
})
@Get()
getHello(): string {
// ...
}
-
ApiResponsespecifies which responses are anticipated, like error responses. NestJS’ Swagger bundle offers decorators for particular standing codes likeApiBadRequestResponse.
// ...
@ApiResponse({ kind: NotFoundException, standing: HttpStatus.NOT_FOUND })
@ApiBadRequestResponse({ kind: BadRequestException })
@Get(':id')
async getById(
@Param('id', new ParseUUIDPipe()) id: string,
): Promise<UserDto> {
return this.userService.findById(id);
}
// ...
-
ApiSecurity('token')makes use of a custom-defined safety technique,tokenon this case. Different choices are to make use of already outlined methods likeApiBearerAuth.
@ApiSecurity('token')
@Controller()
export class AppController {
// ...
}
// ...
@ApiBearerAuth()
@Controller()
export class AppController {
// ...
}
-
ApiExcludeEndpointandApiExcludeControllerexclude one endpoint and the entire controller, respectively.
export class AppController {
@ApiExcludeEndpoint()
@Get()
getHello(): string {
// ...
}
}
// ...
@ApiExcludeController()
@Controller()
export class AppController {
// ...
}
Importing API to Postman
Import JSON model of API docs as Postman API with Import → Hyperlink choice (e.g., URL http://localhost:8081/api-docs-json). Imported API will probably be obtainable within the APIs tab.