Geração de Documentação
- @nestjs/swagger:
@nestjs/swaggergera documentação OpenAPI automaticamente a partir de anotações em controladores e modelos no NestJS. Ele suporta anotações personalizadas para descrever pontos finais, parâmetros e esquemas de resposta. - swagger-ui-express:
swagger-ui-expressnão gera documentação, mas serve uma interface de usuário interativa para visualizar a documentação OpenAPI. Ele requer uma especificação OpenAPI pré-existente para funcionar. - openapi-typescript:
openapi-typescriptnão gera documentação, mas cria tipos TypeScript a partir de uma especificação OpenAPI. Isso ajuda a garantir a conformidade com a API em tempo de compilação, mas não fornece documentação visual. - swagger-jsdoc:
swagger-jsdocgera documentação OpenAPI a partir de comentários JSDoc em seu código. Ele converte anotações JSDoc em uma especificação OpenAPI, que pode ser usada com ferramentas como Swagger UI. - express-openapi-validator:
express-openapi-validatornão gera documentação, mas valida solicitações e respostas com base em uma especificação OpenAPI existente. Ele garante que a API esteja em conformidade com a definição OpenAPI fornecida. - hapi-swagger:
hapi-swaggergera documentação OpenAPI automaticamente a partir de anotações em pontos finais Hapi. Ele permite a personalização das descrições, parâmetros e esquemas diretamente no código.
Validação de API
- @nestjs/swagger:
@nestjs/swaggerfornece validação de esquema básica, mas depende de bibliotecas externas comoclass-validatorpara validação de dados de entrada. Ele se concentra mais na documentação do que na validação. - swagger-ui-express:
swagger-ui-expressnão fornece validação de API. Ele serve uma interface de usuário para visualizar a documentação OpenAPI, mas não valida os dados. - openapi-typescript:
openapi-typescriptnão fornece validação de API. Ele gera tipos TypeScript a partir de uma especificação OpenAPI, mas não valida os dados em tempo de execução. - swagger-jsdoc:
swagger-jsdocnão fornece validação de API. Ele gera documentação OpenAPI a partir de comentários JSDoc, mas não valida os dados de entrada ou saída. - express-openapi-validator:
express-openapi-validatorfornece validação robusta de solicitações e respostas com base em uma especificação OpenAPI. Ele valida automaticamente os dados de entrada e saída, garantindo conformidade com a definição OpenAPI. - hapi-swagger:
hapi-swaggernão fornece validação de API por conta própria, mas pode ser integrado a bibliotecas de validação. Ele se concentra na geração de documentação a partir de anotações de pontos finais.
Integração com Frameworks
- @nestjs/swagger:
@nestjs/swaggeré projetado para integração perfeita com o framework NestJS, aproveitando seu sistema de injeção de dependência e anotações. - swagger-ui-express:
swagger-ui-expressé um middleware para aplicativos Express que serve a interface de usuário do Swagger. Ele pode ser usado com qualquer documentação OpenAPI. - openapi-typescript:
openapi-typescripté uma ferramenta independente que pode ser usada com qualquer projeto JavaScript ou TypeScript. Ele não depende de um framework específico. - swagger-jsdoc:
swagger-jsdocé uma biblioteca independente que pode ser usada com qualquer aplicativo Node.js. Ela gera documentação OpenAPI a partir de comentários JSDoc, independentemente do framework. - express-openapi-validator:
express-openapi-validatoré um middleware independente que pode ser integrado a qualquer aplicativo Express. Ele não é específico de um framework. - hapi-swagger:
hapi-swaggeré projetado para integração com o framework Hapi, aproveitando seu sistema de plugin e anotações de pontos finais.
Exemplo de Código
- @nestjs/swagger:
Exemplo de Geração de Documentação com
@nestjs/swaggerimport { Controller, Get } from '@nestjs/common'; import { ApiTags, ApiResponse } from '@nestjs/swagger'; @ApiTags('cats') @Controller('cats') export class CatsController { @Get() @ApiResponse({ status: 200, description: 'Retorna uma lista de gatos.' }) findAll() { return []; } } - swagger-ui-express:
Exemplo de Uso com
swagger-ui-expressconst swaggerUi = require('swagger-ui-express'); const swaggerDocument = require('./swagger.json'); app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument)); - openapi-typescript:
Exemplo de Geração de Tipos com
openapi-typescriptnpx openapi-typescript path/to/openapi.yaml -o src/types.ts - swagger-jsdoc:
Exemplo de Geração de Documentação com
swagger-jsdocconst swaggerJsDoc = require('swagger-jsdoc'); const swaggerUi = require('swagger-ui-express'); const swaggerOptions = { definition: { openapi: '3.0.0', info: { title: 'API de Exemplo', version: '1.0.0', }, }, apis: ['./routes/*.js'], }; const swaggerDocs = swaggerJsDoc(swaggerOptions); app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs)); - express-openapi-validator:
Exemplo de Validação de API com
express-openapi-validatorconst express = require('express'); const OpenApiValidator = require('express-openapi-validator').OpenApiValidator; const app = express(); app.use(express.json()); app.post('/pets', (req, res) => { res.send(req.body); }); app.use( OpenApiValidator.middleware({ apiSpec: 'path/to/openapi.yaml', validateRequests: true, validateResponses: true, }) ); - hapi-swagger:
Exemplo de Documentação com
hapi-swaggerconst Hapi = require('@hapi/hapi'); const HapiSwagger = require('hapi-swagger'); const { register } = require('hapi-plugin'); const init = async () => { const server = Hapi.server({ port: 3000 }); await server.register([ HapiSwagger, { plugin: HapiSwagger, options: { info: { title: 'API de Exemplo', version: '1.0.0', }, }, }, ]); server.route({ method: 'GET', path: '/pets', handler: () => [{ name: 'Fido' }], options: { tags: ['api'], description: 'Retorna uma lista de animais de estimação', }, }); await server.start(); console.log('Servidor em execução em %s', server.info.uri); }; init();