¿Qué es swagger?

Si estas buscando la forma de documentar tu API, swagger es lo que buscas, es justamente eso.

Swagger es un framework para documentar APIs Rest desde muy diferentes fuentes: Archivos de configuración, XML, C#, Javascript, Ruby, PHP, Java, Scala… además existen multitud de módulos que te pueden ayudar a integrarlo en tu proyecto.

Con swagger puedes describir, producir, consumir y visualizar APIs, por lo que te será interesante como desarrollador de tu proyecto, pero también desde el punto de vista de un tercero que pudiese consumir tu API, o un usuario que busca información sobre un error o como tu API esta construida, o un tester de tu equipo que quiere probar la funcionalidad de backend como primera medida para excluir un fallo en esta lado para centrarse en Frontend o no.

Si además usas microservicios, puedes paliar varias de las “desventajas” de usar esta arquitectura usando una API bien documentada, pero de esto hablaré en otra entrada.

A continuación os dejo la url del site de swagger.

Como desarrollador de .Net puedo deciros que ha sido un descubrimiento fantástico. En mis proyectos personales ya comencé a ver el potencial que tenía, pero ha sido con un cambio a un nuevo proyecto profesional, que ya lo integraba, cuando me he dado cuenta de que no era una suposición, es MUY útil y agiliza mucho el trabajo, en especial si lo mantenemos debidamente actualizado y explotando todas sus propiedades.

Esta actualización de la descripción de los endpoints puede hacerse con data annotations integradas en nustro código c# y con XML autogenerado desde visual studio al compilar los proyectos, usando la documentación que sueles incluir en los métodos (o deberías) en sus secciones ///Summary. Esto no será visible en la configuración básica, de la que hablo en esta entrada sobre cómo instalar swagger en tu WebApi.

Estas propiedades extendidas de las que hablo te van a permitir por ejemplo:

  • Autenticación con OAuth desde la interfaz de swagger para consumir endpoints que requieran header de Authentication por bearer token.
  • Presentar los modelos de los objetos devueltos o requieridos como entrada en post, put o patch.
  • Preconfigurar ejemplos de estos objetos, de forma que puedan ser utilizados muy rápidamente, no necesitando construir un modelo válido para cada petición.
  • Describir la funcionalidad del endpoint.
  • Añadir implementation notes útiles como información adicional.
  • Mencionar el tipo de respuestas Http que el endpoint puede producir y sus objetos contenidos.
  • Describir cada uno de los parámetros de entrada.
  • Obtener un documento yaml de tus endpoints que poder importar en postman o fiddler

¿No esta mal a cambio de unas pocas líneas de código adicionales en tu webapi verdad?

Iré desglosando en entradas posteriores estas posibilidades, si te interesa, no dejes de estar atento al blog.

Deja un comentario