https://github.com/ssukienn/nestjs-swagger-api-spec

Decorator for aggregating all your @nestjs/swagger decorators.
https://github.com/ssukienn/nestjs-swagger-api-spec

decorator nestjs openapi swagger typescript utility

Last synced: about 2 months ago
JSON representation

Decorator for aggregating all your @nestjs/swagger decorators.

• Host: GitHub
• URL: https://github.com/ssukienn/nestjs-swagger-api-spec
• Owner: ssukienn
• License: mit
• Created: 2023-10-08T15:34:14.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2024-03-31T00:09:14.000Z (9 months ago)
• Last Synced: 2024-11-15T04:04:32.391Z (about 2 months ago)
• Topics: decorator, nestjs, openapi, swagger, typescript, utility
• Language: TypeScript
• Homepage: https://www.npmjs.com/package/nestjs-swagger-api-spec
• Size: 134 KB
• Stars: 2
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

        
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` decorators. Decorator order is determined by ECMAScript iteration order for keys and can be adjusted using order suffixes.

### Example

```typescript

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.

## Getting Support & Contributing

* Open issues or pull requests for support or contributions.

## License

- [MIT licensed](LICENSE).