¿Alguna vez has querido tener una documentación de swagger para tu API express basada en anotaciones? Yo tengo Y desafortunadamente no encontré ninguna forma de hacerlo sin tener que crear manualmente un archivo swagger.json . Mi deseo era simple como este: quiero tener una aplicación express limpia con múltiples puntos finales y quiero mantener una documentación swagger para cada punto final cercano a la implementación del punto final, no en un archivo separado.

Tal vez solo me faltan algunas habilidades de Google, pero decidí que sería mucho más fácil para mí crear dicha herramienta. Y aquí está: mgr-swagger-express

Empezando

El ejemplo aquí se escribirá en TypeScript, pero lo mismo se puede hacer en un proyecto Javascript.
Así que imagina una aplicación express clásica:

Aquí tenemos un recurso "Libro" y algunos puntos finales CRUD básicos. La pregunta es "¿Cómo agregaría una documentación genial de Swagger a esta API?" Realmente quería hacerlo usando anotaciones para mantener cada documentación de punto final cerca del punto final en sí.

Esto es lo que podrá hacer con mgr-swagger-express :
index.ts :

BookService.ts :

Hay un código más bot, pero ahora tenemos toda la documentación de swagger cerca del punto final.
Veamos qué está pasando aquí:

• En el archivo de índice, creamos la aplicación express, como de costumbre. También tenemos que inicializar todos los middlewares (el bodyParser es el más importante).
• Después de esto, llamamos a SET_EXPRESS_APP para configurar el objeto de la aplicación de forma global. De esta forma, mgr-swagger-express podrá adjuntar controladores a puntos finales
• Solo después de esto podemos importar el servicio con anotaciones. No tiene que ser una clase, podría ser solo funciones.
• Luego creamos una instancia de nuestro servicio (o llamamos a una función init en caso de no usar clases)
• Y generamos una configuración swagger basada en todas las anotaciones que tenemos en el proyecto y la adjuntamos a nuestra aplicación usando el paquete swagger-ui-express

Dentro del servicio, están ocurriendo varias cosas, pero detengámonos solo en un par de ellas. Todo lo demás que puede encontrar fácilmente en el repositorio mgr-swagger-express:

• En el constructor llamamos a la función addSwaggerDefinition . Registra un modelo swagger con un nombre de pila. en nuestro caso, definimos BookDefinition bajo el nombre de un Libro para luego hacer referencia a él por #/definitions/Book
• Todos los controladores se anotan con los @GET @POST @PUT @DELETE . Todos ellos están tomando en argumentos un objeto de tipo SwaggerEndpoint :
  

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

  
  

  Básicamente es el objeto de definición de punto final swagger clásico, nada especial, excepto el campo de autenticación, pero volveré sobre él en el futuro

  
  Todos los manejadores deben tener la siguiente firma:
  

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

  
  

  El objeto args contiene todos los parámetros aplicados a su punto final. Pueden ser parámetros de URL (como book_id en nuestro ejemplo), parámetros de consulta o incluso el valor del cuerpo.

  
  
  

  El objeto de contexto se usa para manejar la autenticación y la seguridad, pero nuevamente, más adelante.

  
  

  Conclusión

  
  

  Ahora tenemos una API CRUD express simple anotada con Swagger y una hermosa interfaz de usuario swagger, donde todas las definiciones de Swagger se encuentran cerca de la implementación del punto final. Como de costumbre, ¡siempre me alegra recibir comentarios! ️