Documentando una API con Swagger y .NET Core.
Swagger es un herramienta súper poderosa que fácilmente puede integrarse a una API. Es una manera de llevar la documentación prolija, al día y con una interfaz amigable. Puede configurarse de distintas maneras, una fácil y copada es usando Swashbucle.
"Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated from your OpenAPI (formerly known as Swagger) Specification, with the visual documentation making it easy for back end implementation and client side consumption."
El primer paso es agregar el paquete nuget a nuestra API. Para ello, podemos usar la consola o buscarlo desde el administrador. En este caso voy a correrlo desde la consola.
Una vez instalado en nuestra solución, para configurar el middleware en nuestra solución tenemos que hacer las siguientes modificaciones en la clase startup.cs. Primero el método Configure.
Luego, en el método ConfigureServices.
En estos momentos ya estamos en condiciones de realizar nuestra primera prueba de Swagger, ejecutamos la API, con una configuración por default.
El endpoint lo podemos configurar como argumento del método de extensión .SwaggerEndpoint, donde queremos quede configurado. En la última imagen vemos configuración extra, la cual es importante si queremos que el usuario tenga conocimiento acerca de los términos de uso, algún contacto y licencias.
Otra herramienta interesante de Swagger es la configuración XML que puede darle a los controladores y endpoints mayor completitud de información a la API. En este articulo voy a comentar las siguientes configuraciones: Descripciones a métodos, ejemplos de requests, parámetros requeridos, descripción extra de parámetros, type de respuesta y configuración de código de respuesta. Empecemos con la configuración XML. Para esto es necesario agregar al método ConfigureServices dentro del método de extensión .SwaggerDoc, las siguientes lineas:
Por otro lado y para no recibir warnings molestos, agregar las siguientes lineas al archivo .csproj.
Hecho esto, estamos en condiciones de empezar a trabajar con nuestros endpoints y controlador/es. Trabajaremos con los siguientes decoradores:
- remarks
- summary
- param
- response
remarks es muy útil cuando queremos dar al usuario un ejemplo de como debe ser el request. Veamos como implementarlo desde el controlador. Para ello, es necesario agregar las siguientes lineas al método.
summary cuando queremos darle al usuario un detalle en profundidad de cual es comportamiento funcional de un método.
param detalla los parámetros del método, en caso de que este lo necesite.
response nos permite manejar distintos código de respuesta en forma detallada. Veamos el siguiente ejemplo, donde manejamos dos códigos de respuesta distintos.
En resumen Swagger es muy útil para poder darle al usuario una completa utilización de la API. Ofrece una interfaz agradable y fácil de utilizar. Para mayor profundidad de las tools que ofrece Swagger dirigirse al siguiente enlace.