Documentando nuestros APIs REST ASP.NET Core con Swagger

Hoy os quiero hablar de unas herramientas muy prácticas cuando nos encontramos desarrollando API REST. Se trata de Swagger y SwaggerUI. Estas herramientas, entre otras muchas utilidades, nos van a permitir documentar nuestras API de forma muy sencilla y práctica.

¿Qué es Swagger?

Swagger es un framework extremadamente potente para el desarrollo de APIs RESTful. Dispone de varias herramientas destinadas a facilitar nuestro trabajo con este tipo de APIs. Por ejemplo, disponemos de Swagger Editor para diseñar el interfaz de nuestra API, usando YAML, un lenguaje de marcado que nos permitirá describir nuestro API a la perfección. Después existe un generador de código que se ocupará de crear un proyecto, para varios lenguajes y plataformas, entre las que se encuentra C#.

Además, hay numerosas herramientas, desarrolladas por terceros, que nos van a permitir ampliar sus capacidades.

Swagger UI

Por último, disponemos de SwaggerUI, una herramienta que nos va a permitir generar documentación para nuestro API, de forma que dispondremos de una pequeña web, muy similar a la que podíamos usar con los servicios web WCF o ASMX. Desde esta pequeña web, podremos incluso invocar nuestro API, a modo de sandbox.

Uso de SwaggerUI con ASP.NET Core

Vamos a realizar una instalación básica de SwaggerUI sobre el ejemplo básico de Web API de ASP.NET Core, para ver cómo puede ayudarnos en nuestro trabajo. Comenzaremos por crear un proyecto nuevo de API Web con ASP.NET Core.

A continuación, instalaremos los paquetes necesarios para utilizar Swagger y SwaggerUI. Por comodidad, utilizaremos Swashbuckle, un paquete que tiene integrado todo lo necesario para comenzar, de forma rápida y fácil.

Es muy importante observar que, actualmente, la versión para ASP.NET Core de esta herramienta se encuentra en desarrollo, por lo que todavía le faltan funciones que si están presentes en la versión para ASP.NET 5. No obstante, servirá para la mayoría de nuestros proyectos.

1.- Instalación de los paquetes necesarios

Añadiremos el paquete Swashbuckle.AspNetCore, especificando que incluya versiones preliminares en el administrador de paquetes.

2.- Configuración inicial

Una vez instalados los paquetes necesarios, podemos empezar a configurar las funciones básicas. Para ello, añadiremos la configuración del generador de Swagger en la clase Startup:

Podemos definir atributos básicos, como el título de nuestro API, versión, una breve descripción, etc.

En el método “Configure” añadiremos el middleware correspondiente, para asegurar su carga en tiempo de ejecución:

Ya podemos ejecutar la aplicación. Si cargamos la URL /swagger en un navegador, veremos la página de documentación de nuestro API:

3.- Inclusión de comentarios XML

Con esto ya tendríamos funcionando SwaggerUI de forma muy básica. Pero para disponer de algo más útil, debiera aparecer en esta página alguna descripción de los verbos HTTP, el formato de los parámetros de entrada o salida, etc.

Lo mejor para ello es aprovechar los comentarios XML de nuestro proyecto. Para ello, primero debemos habilitar la generación de comentarios XML al compilar. Esto lo podemos hacer en las propiedades del proyecto.

A continuación, para incluir estos comentarios en la documentación de Swagger, debemos editar de nuevo el método ConfigureServices:

De esta forma, podremos convertir esto

en esto:

Existen muchísimas más opciones que nos van a permitir afinar mucho el contenido de esta documentación, así como multitud de herramientas externas que nos pueden facilitar mucho la vida, pero eso requeriría un post muchísimo más extenso. Para ampliar más esta información, os recomiendo consultar la excelente documentación del proyecto. Os dejo unos enlaces que seguro que os resultan muy útiles para aprender más sobre esta fantástica herramienta.

Página principal del proyecto: http://www.swagger.io

Documentación de Swashbuckle: https://github.com/domaindrivendev/Swashbuckle.AspNetCore

jose-manuel-morillas-fotoJosé Manuel Morillas Navarro

.NET Senior Developer| Soluciones Microsoft | SOGETI ESPAÑA

 

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s