Você já desejou ter uma documentação arrogante para sua API expressa com base em anotações? Eu tenho. E, infelizmente, não encontrou nenhuma maneira de fazer isso sem ter que criar manualmente um arquivo swagger.json . Meu desejo era simples assim: eu quero ter um aplicativo expresso limpo com vários pontos de extremidade e quero manter a documentação arrogante para cada ponto de extremidade próximo à implementação do ponto de extremidade, não em um arquivo separado.

Talvez eu apenas tenha algumas habilidades no Google, mas decidi que seria muito mais fácil criar uma ferramenta desse tipo. E aqui está: mgr-swagger-express

Introdução

O exemplo aqui será escrito em TypeScript, mas o mesmo pode ser feito no projeto Javascript.
Imagine um aplicativo expresso clássico:

Aqui temos um recurso "Livro" e alguns pontos finais CRUD básicos. A pergunta é: "Como você adicionaria uma documentação legal do Swagger a essa API?" Eu realmente queria fazer isso usando anotações para manter toda a documentação do terminal próxima ao próprio terminal.

Isto é o que você poderá fazer com o mgr-swagger-express :
index.ts :

BookService.ts :

Há um código a mais, mas agora temos toda a documentação do swagger, que fica perto do próprio ponto final.
Vamos ver o que está acontecendo aqui:

• No arquivo de índice, criamos um aplicativo expresso, como de costume. Também temos que inicializar todos os middlewares (o bodyParser é o mais importante).
• Depois disso, chamamos o SET_EXPRESS_APP para definir o objeto do aplicativo globalmente. Dessa forma, o mgr-swagger-express poderá anexar manipuladores aos terminais
• Somente depois disso podemos importar o serviço com anotações. Não precisa ser uma classe, pode ser apenas funções.
• Em seguida, criamos uma instância do nosso serviço (ou chamamos uma função init no caso de não usar classes)
• E geramos a configuração do swagger com base em todas as anotações que temos no projeto e as anexamos ao nosso aplicativo usando o pacote swagger-ui-express

Dentro do serviço, há várias coisas acontecendo, mas vamos parar apenas em algumas delas. Tudo o que você pode encontrar facilmente no repositório mgr-swagger-express:

• No construtor, chamamos a função addSwaggerDefinition . Ele registra um modelo de arrogância com um determinado nome. no nosso caso, definimos BookDefinition sob o nome de um livro para referenciá-lo posteriormente por #/definitions/Book BookDefinition #/definitions/Book
• Todos os manipuladores são anotados com os @GET @POST @PUT @DELETE . Todos eles estão recebendo argumentos um objeto do tipo SwaggerEndpoint :
  

   path: string; auth?: string; description?: string; tags?: string[]; parameters?: SwaggerURLParameter[]; query?: SwaggerQueryParameter; body?: SwaggerBodyParameter; success?: SwaggerSuccessResponse; 

  
  

  É basicamente o objeto clássico de definição de ponto final swagger, nada de especial, exceto o campo auth, mas voltarei a ele no futuro

  
  Todos os manipuladores devem ter a seguinte assinatura:
  

   (args: object, context: Context) => Promise<any> 

  
  

  O objeto args contém todos os parâmetros direcionados ao seu terminal. Pode ser parâmetros de URL (como book_id em nosso exemplo), parâmetros de consulta ou até mesmo valor do corpo.

  
  
  

  O objeto de contexto é usado para lidar com autenticação e segurança, mas novamente, sobre isso mais tarde.

  
  

  Conclusão

  
  

  Agora, temos uma API expressa CRUD simples anotada com o Swagger e uma bela interface do usuário do swagger, na qual todas as definições do Swagger estão próximas da implementação do terminal. Como de costume - sempre feliz em ter algum feedback! ️