managing-swagger-recipe

Swagger with Andercore Toolkit

Quick Reference

Config	Purpose	Example
bootstrap({ swagger })	Setup Swagger UI	bootstrap({ swagger: {...} })
title	API title	'User Service API'
description	API description	'User management'
path	Swagger UI path	'api-docs'
supportedVersions	Filter versions	['0', '1']

When to Use

Swagger setup | OpenAPI configuration | version filtering | API docs path

Toolkit Features

What @andercore/toolkit provides:

• Unified Swagger configuration via bootstrap()
• Automatic SwaggerModule setup
• Version filtering integration
• Path customization

What toolkit does NOT provide:

• Decorators (@ApiTags, @ApiOperation, @ApiProperty, etc.) → Use @nestjs/swagger
• DTO documentation → See typescript-services:nestjs-recipe
• Controller documentation → See typescript-services:nestjs-recipe

Setup

→ See andercore-toolkit-services:bootstrap-recipe for complete bootstrap patterns

Via bootstrap():

import { bootstrap } from '@andercore/toolkit'

bootstrap({
  appModule: AppModule,
  swagger: {
    title: 'User Service API',
    description: 'Comprehensive user management API',
    version: '1.0.0',
    path: 'api-docs',
    supportedVersions: ['0', '1']
  },
  versioning: {
    type: 'uri',
    prefix: 'v'
  }
})

Access: http://localhost:3000/api-docs

Configuration Options

Option	Required	Default	Purpose
title	✓	-	API title in Swagger UI
description	✓	-	API description
version	✗	'1.0.0'	API version displayed
path	✗	'document'	Swagger UI endpoint path
supportedVersions	✗	undefined	Version filter (see below)

Version Filtering (TOOLKIT-SPECIFIC)

Feature: Filter Swagger docs by controller versions

Pattern:

bootstrap({
  swagger: {
    title: 'API',
    description: 'Versioned API',
    version: '2.0.0',
    supportedVersions: ['1', '2']  // Only includes v1 and v2 controllers
  },
  versioning: {
    type: 'uri',
    prefix: 'v'
  }
})

Controller versioning:

// Included in Swagger (version '1')
@Controller({ path: 'users', version: '1' })
export class UsersV1Controller {}

// Included in Swagger (version '2')
@Controller({ path: 'users', version: '2' })
export class UsersV2Controller {}

// Excluded from Swagger (version '0')
@Controller({ path: 'users', version: '0' })
export class UsersV0Controller {}

Result: Swagger UI only shows endpoints from controllers with version '1' or '2'

Without supportedVersions:

bootstrap({
  swagger: {
    title: 'API',
    description: 'All versions'
    // supportedVersions omitted
  }
})
// Result: All controller versions included in Swagger

Path Customization

Default path:

bootstrap({
  swagger: {
    title: 'API',
    description: 'Description'
  }
})
// Access: http://localhost:3000/document

Custom path:

bootstrap({
  swagger: {
    title: 'API',
    description: 'Description',
    path: 'api-docs'
  }
})
// Access: http://localhost:3000/api-docs

Nested path:

bootstrap({
  swagger: {
    title: 'API',
    description: 'Description',
    path: 'docs/api/v1'
  }
})
// Access: http://localhost:3000/docs/api/v1

Integration with Versioning

→ See andercore-toolkit-services:bootstrap-recipe for versioning strategies

URI versioning:

bootstrap({
  swagger: {
    title: 'API',
    supportedVersions: ['1', '2']
  },
  versioning: {
    type: 'uri',
    prefix: 'v'
  }
})
// Routes: /v1/users, /v2/users
// Swagger shows both

Header versioning:

bootstrap({
  swagger: {
    title: 'API',
    supportedVersions: ['1']
  },
  versioning: {
    type: 'header',
    header: 'X-API-Version'
  }
})
// Header: X-API-Version: 1
// Swagger shows v1 controllers

Media type versioning:

bootstrap({
  swagger: {
    title: 'API',
    supportedVersions: ['1']
  },
  versioning: {
    type: 'media_type',
    key: 'v='
  }
})
// Accept: application/json;v=1
// Swagger shows v1 controllers

Controller & DTO Documentation

→ typescript-services:nestjs-recipe for:

• @ApiTags, @ApiOperation, @ApiResponse
• @ApiProperty, @ApiPropertyOptional
• @ApiBearerAuth, @ApiSecurity
• @ApiParam, @ApiQuery, @ApiBody
• DTO schema documentation
• Authentication schemes

Quick example (see nestjs-recipe for complete patterns):

import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger'

@ApiTags('users')
@Controller({ path: 'users', version: '1' })
export class UsersController {
  @ApiOperation({ summary: 'Get user' })
  @ApiResponse({ status: 200, type: UserDto })
  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.service.findOne(id)
  }
}

Environment-Specific Setup

Disable in production:

bootstrap({
  swagger: process.env.NODE_ENV !== 'production' ? {
    title: 'Dev API',
    description: 'Development API'
  } : undefined
})

Different configs per environment:

const swaggerConfig = {
  development: {
    title: 'Dev API',
    description: 'Development environment',
    path: 'api-docs'
  },
  staging: {
    title: 'Staging API',
    description: 'Staging environment',
    path: 'docs'
  }
}

bootstrap({
  swagger: swaggerConfig[process.env.NODE_ENV]
})

Testing

Verify Swagger endpoint:

import { Test } from '@nestjs/testing'
import { INestApplication } from '@nestjs/common'
import request from 'supertest'

describe('Swagger', () => {
  let app: INestApplication

  beforeEach(async () => {
    const module = await Test.createTestingModule({
      imports: [AppModule]
    }).compile()

    app = module.createNestApplication()
    await app.init()
  })

  it('serves Swagger UI', async () => {
    const response = await request(app.getHttpServer())
      .get('/api-docs')
      .expect(200)

    expect(response.text).toContain('swagger-ui')
  })

  it('serves OpenAPI JSON', async () => {
    const response = await request(app.getHttpServer())
      .get('/api-docs-json')
      .expect(200)

    expect(response.body).toHaveProperty('openapi')
    expect(response.body).toHaveProperty('info')
    expect(response.body.info.title).toBe('User Service API')
  })
})

Validation Checklist

CHECK:
- [ ] bootstrap({ swagger: {...} }) configured?
- [ ] title and description provided?
- [ ] path customized if needed?
- [ ] supportedVersions matches controller versions?
- [ ] Versioning strategy configured (if using version filtering)?
- [ ] Swagger disabled in production (if required)?
- [ ] /api-docs accessible in development?

TOOLKIT-SPECIFIC:
- [ ] Using bootstrap() for Swagger setup (not manual SwaggerModule)?
- [ ] Version filtering via supportedVersions (if multi-version API)?
- [ ] @nestjs/swagger decorators used directly (not custom toolkit decorators)?

VIOLATIONS:
- Manual SwaggerModule.setup() → Use bootstrap({ swagger })
- Missing version in @Controller() when using supportedVersions → Add version
- Swagger enabled in production → Disable or protect endpoint

Advanced Topics

See bootstrap-recipe for:

• Complete bootstrap configuration
• Versioning strategies
• CORS integration
• Global validation

See nestjs-recipe for:

• Complete decorator patterns
• DTO documentation
• Authentication schemes
• Response schemas
• Error documentation

Reference

Toolkit provides:

• bootstrap({ swagger }) - Unified Swagger configuration
• supportedVersions - Version filtering (TOOLKIT-SPECIFIC)
• path - UI path customization

Toolkit does NOT provide:

• Decorators - Use @nestjs/swagger
• Schema generation - Use @nestjs/swagger
• Custom OpenAPI utilities - Use @nestjs/swagger

External docs:

• NestJS OpenAPI: https://docs.nestjs.com/openapi/introduction
• OpenAPI Spec: https://swagger.io/specification/