nestjs-swagger-docs

What problem does it solve?

This Skill unit ensures that NestJS controllers and endpoints are documented with best practices, improving consistency and reducing errors in Swagger/OpenAPI annotations.

Core Features & Use Cases

• Best Practices Guide: Provides guidelines for @ApiResponse decorators, Swagger schema examples, and shared error response decorators.
• Real-time Response Validation: Ensures documented response shapes match actual runtime output.
• Shared Error Decorators: Encourages reusability and standardization of error responses across endpoints.
• Quick Documentation Procedures: Offers step-by-step guidance for documenting new endpoints and updating existing ones.
• Decorator Order Convention: Suggests an order for API decorators to maintain clarity and consistency.

Quick Start

To document a new endpoint, follow these steps:

1. Read the service method to understand the return type and fields.
2. Write the 200 @ApiResponse with a schema.example including the full ApiResponseDto envelope and all data fields.
3. Add endpoint-specific non-2xx codes with schema.example.
4. Apply the shared error decorator as the last decorator before the method.
5. Verify the @ApiTags class decorator exists and the tag is registered in main.ts.