Nestjs-swagger-api-spec NPM

Motivation

Simplify the management of @Controller classes and methods (e.g., @Get route handler) by addressing the issue of OpenAPI decorators pollution from @nestjs/swagger. This library provides a streamlined approach to apply all relevant OpenAPI decorators using a single decorator.

Requirements

minimal @nestjs/common@^7.6.0
minimal @nestjs/swagger@^4.8.1

For specific version details, refer to package.json.

Usage

1. Install the Dependency

$ npm install nestjs-swagger-api-spec

2. Use `@ApiSpecification` Decorator

Apply the @ApiSpecification decorator to controllers or handlers to automatically add relevant @Api<name> decorators. Decorator order is determined by ECMAScript iteration order for keys and can be adjusted using order suffixes.

Example

import { ApiSpecification, ApiOptions } from 'nestjs-swagger-api-spec';

const exampleSpec: ApiOptions = {
    apiResponseOptions: (apiDecorator) => apiDecorator({ status: 200, description: "Applied in the middle, defined first." }),
    apiOperationOptions1: (apiDecorator) => [
        apiDecorator({
            summary: "title",
            description: "3",
        }),
        apiDecorator({ summary: "title", description: "Applied last, defined in the middle." }),
    ],
    'apiOperationOptions-1': (apiDecorator) => apiDecorator({ status: 200, description: "Applied first, defined last." },
    //...
}

@ApiSpecification(exampleSpec)
@Controller()
class Example {
    
    @Get()
    @ApiSpecification({
        apiOperationOptions1: (apiDecorator) => apiDecorator({
            summary: "customTitle",
            description: "customDescription",
        }),
        // Additional decorators...
    })
    getExample() {
        //...
    }
}

Decorator Ordering

The order of decorators can be customized by adding a suffix number to the options properties. Positive numbers define the order in ascending fashion, while negative numbers represent the order in descending fashion. For instance, apiOperationOptions1 and 'apiOperationOptions-1' will apply decorators in different orders. Default order is 0.

Caveats

Decorator factories must be named with the Api prefix.
Using property names with a format other than expected may result in errors.
ApiProperty, ApiPropertyOptional, and ApiHideProperty decorators are not supported for route handler decorators.
Future Nest versions breaking the contract of applyDecorators may impact the implementation.