Swagger / OpenAPI

O PlazerCLI configura Swagger UI com especificacao OpenAPI 3.0 acessivel em /api/docs. A documentacao inclui todos os endpoints, schemas, autenticacao Bearer JWT e permite testar endpoints diretamente pela interface.

Apos iniciar o servidor, acesse:

• Swagger UI: http://localhost:3001/api/docs
• OpenAPI JSON: http://localhost:3001/api/docs/json (Express)

A interface vem com:

• Autenticacao JWT persistente (persist authorization)
• Filtro de endpoints por tag
• Medicao de tempo de resposta
• Syntax highlighting (tema Monokai)
• Endpoints colapsados por padrao

Usa o modulo oficial @nestjs/swagger com decorators:

// apps/api/src/common/swagger/swagger.config.ts
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';

export function setupSwagger(app: INestApplication): void {
  const config = new DocumentBuilder()
    .setTitle('meu-projeto')
    .setDescription('API documentation')
    .setVersion('1.0')
    .addBearerAuth({
      type: 'http',
      scheme: 'bearer',
      bearerFormat: 'JWT',
    }, 'access-token')
    .addTag('health')
    .addTag('auth')
    .addTag('users')
    .build();

  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api/docs', app, document);
}

// Chamado no main.ts:
setupSwagger(app);

Para documentar endpoints NestJS, use decorators:

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

@ApiTags('users')
@ApiBearerAuth('access-token')
@Controller('users')
export class UsersController {
  @Get()
  @ApiResponse({ status: 200, description: 'Lista de usuarios' })
  findAll() { ... }
}

Usa swagger-jsdoc com comentarios @openapi nos arquivos de rota:

// apps/api/src/config/swagger.ts
import swaggerJsdoc from 'swagger-jsdoc';
import swaggerUi from 'swagger-ui-express';

const swaggerSpec = swaggerJsdoc({
  definition: {
    openapi: '3.0.3',
    info: { title: 'meu-projeto', version: '1.0.0' },
    components: {
      securitySchemes: {
        bearerAuth: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
      },
    },
  },
  apis: ['./src/routes/**/*.ts', './src/**/*.routes.ts'],
});

export function setupSwagger(app: Express): void {
  app.use('/api/docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
  app.get('/api/docs/json', (_req, res) => res.json(swaggerSpec));
}

Para documentar endpoints, use JSDoc:

/**
 * @openapi
 * /api/users:
 *   get:
 *     tags: [users]
 *     summary: Lista todos os usuarios
 *     security:
 *       - bearerAuth: []
 *     responses:
 *       200:
 *         description: Lista de usuarios
 */
router.get('/users', handler);

Plugin Fastify com @fastify/swagger e @fastify/swagger-ui:

// apps/api/src/plugins/swagger.ts
async function swaggerPlugin(app: FastifyInstance) {
  await app.register(swagger, {
    openapi: {
      openapi: '3.0.3',
      info: { title: 'meu-projeto', version: '1.0.0' },
      components: {
        securitySchemes: {
          bearerAuth: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
        },
      },
    },
  });

  await app.register(swaggerUi, {
    routePrefix: '/api/docs',
    uiConfig: { persistAuthorization: true },
  });
}

Para documentar endpoints Fastify, use o schema da rota:

app.get('/users', {
  schema: {
    tags: ['users'],
    summary: 'Lista todos os usuarios',
    security: [{ bearerAuth: [] }],
    response: {
      200: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            id: { type: 'string' },
            email: { type: 'string' },
          },
        },
      },
    },
  },
}, handler);

O PlazerCLI configura 3 tags iniciais na documentacao:

Tag	Descricao
health	Health check endpoints
auth	Authentication endpoints
users	User management endpoints

Adicione mais tags conforme cria novos modulos (orders, products, billing, etc.).