Swagger Decorators

Uma biblioteca de decoradores em TypeScript para gerar documentação Swagger de forma automática para APIs. Simplifica a criação de definições de rota, parâmetros, e respostas usando decoradores, permitindo uma documentação mais clara e fácil de manter.

Sumário

• Instalação
• Configurações
• Uso
  • Definindo Controladores e Rotas
  • Especificando Parâmetros
  • Especificando Corpo de Requisição
  • Definindo Respostas
• Exemplo Completo
• Contribuindo
• Licença

Instalação

Primeiro, instale a biblioteca com o seguinte comando:

npm install swagger-decorators-express

Configurações

No seu arquivo tsconfig.json habilite essas duas configurações, para que seja possível o uso dos decorators.

 "experimentalDecorators": true,
 "emitDecoratorMetadata": true

No arquivo principal da sua api index.ts por exemplo, importe as funções para gerar o swagger.

import { generateSwaggerDocs } from "swagger-decorators";

const { swaggerUiServe, swaggerUiSetup } = generateSwaggerDocs(
      [new ExampleController()],
      {
        openapi: "3.0.0",
        info: {
          title: "API Example",
          version: "1.0.0",
          description: "API Documentation",
        },
      }
    );
this.app.use("/docs", swaggerUiServe, swaggerUiSetup);

Uso

Definindo Controladores e Rotas

import { ControllerDocs, RouteDocs } from 'swagger-decorators';

@ControllerDocs('/example')
export class ExampleController {
  @RouteDocs({
    path: '/',
    method: 'get',
    summary: 'Get example',
    description: 'Retrieve example data',
  })
  getExample() {
    return { message: 'Hello, World!' };
  }

  @RouteDocs({
    path: '/create',
    method: 'post',
    summary: 'Create example',
    description: 'Create new example entry',
  })
  createExample() {
    return { message: 'Created!' };
  }
}

Especificando Parâmetros

const parameters = [
  {
    in: 'header',
    name: 'api-key',
    required: true,
    schema: {
      type: 'string',
      example: 'my-api-key',
    },
  },
];

Especificando Corpo de Requisição

const requestBody = {
  content: {
    'application/json': {
      schema: {
        type: 'object',
        properties: {
          email: { type: 'string' }
        },
        example: {
          email: '[email protected]'
        },
      },
    },
  },
};

Definindo Respostas

const responses: Responses = {
  200: {
    description: 'Operação realizada com sucesso.',
    content: {
      'application/json': {
        schema: {
          type: 'object',
          properties: {
            id: { type: 'number', example: 1 },
            value: { type: 'number', example: 10 },
            type: { type: 'string', example: 'example' },
          },
        },
      },
    },
  },
  default: {
    description: 'Erro inesperado',
  },
};

Exemplo completo

import { ControllerDocs, RouteDocs } from 'swagger-decorators';

@ControllerDocs('/client')
export class ClientController {
  @RouteDocs({
    path: '/edit',
    method: 'put',
    summary: 'Edita as informações de um cliente',
    tags: ['Client'],
    parameters: [
      {
        in: 'header',
        name: 'security-key',
        required: true,
        schema: {
          type: 'string',
          example: 'my-api-key',
        },
      },
    ],
    requestBody: {
      content: {
        'application/json': {
          schema: {
            type: 'object',
            properties: {
              email: { type: 'string' },
              phone: { type: 'string' }
            },
            example: {
              email: '[email protected]',
              phone: '1234567890'
            },
          },
        },
      },
    },
    responses: {
      200: {
        description: 'Informações do cliente editadas com sucesso.',
      },
      default: {
        description: 'Erro ao editar as informações do cliente.',
      },
    },
  })
  editClient() {
    return { message: 'Cliente atualizado!' };
  }
}

Contribuindo

Sinta-se à vontade para abrir issues ou pull requests para melhorias e correções. Feedback e sugestões são bem-vindos

Licença

Este arquivo fornece uma documentação detalhada da instalação, uso e principais recursos da biblioteca, com exemplos práticos para que outros desenvolvedores possam usar sua biblioteca facilmente.