OpenAPI

¿Que es OpenAPI?

Como todos sabemos una API (Application Programming Interface) es un gran conjunto de procedimientos y protocolos con el fin de poder ser utilizados en diversos Software para que se comuniquen con otros Software.

La finalidad del OpenAPI es generar una estructura genérica para el apoyo de la documentación de un servicio REST, sin importar sobre que lenguaje o tecnología  se allá implementado. Los principales puntos que este llevaría son:

• Descripción de un servicio. 
• Detallar las capacidades de una API. 
• Conocer los detalles del funcionamiento de una API.

Lo cual todo esto nos permite:

• Generar páginas de documentación automáticamente.
• Herramientas de diseño y modelado de servicios.
• Generar automáticamente código de testing y de validaciones.
• Generar código cliente y de servicio, framework y lenguajes programación.

En resumen OpenAPI nos permite definir y comprender las capacidades de un

servicio o una API sin la necesidad de acceder al código fuente.

Swagger... ¿es necesario? 

Definitivamente es necesario; de hecho Swagger es el antecesor de OpenAPI.

Creado por la compañía SmartBear la cual puso los dos primeros estándares de la  especificación OpenAPI. Tiempo después la compañía dono la iniciativa y se creo  la dicha OpenAPI. Al final el framework más común para el uso es Swagger.

Este mismo nos permitirá crear una página web con toda la documentación de

nuestra API con la especificación OpenAPI.

Estructura de OpenAPI.

La estructura se puede escribir en formato JSON o YAML, pongamos de ejemplo el  siguiente código generado desde ASP.Net Core MVC:

La especificación OpenAPI en un JSON del ejemplo anterior, debería de quedar de la siguiente manera:

De esta forma tan “sencilla” queda claro lo que realiza nuestro servicio.

También podemos generar en automático nuestro código de OpenAPI con el
paquete NuGet Swashbuckle.AspNetCore; obviamente para servicios creados con ASP.Net Core. 

Una vez instalado el paquete Swashbuckle de ASP.NET Core solo debemos agregar el servicio en el inyector de dependencias de nuestro proyecto en ASP.Net Core:

En la llamada SwaggerDoc() deberá ir el nombre que le daremos al documento
generado y alguna otra información como por ejemplo la versión, los cuales se
mostraran en el documento OpenAPI. 

Posteriormente como podemos ver en el código indicamos al componente en
donde puede encontrar el archivo XML con la documentación de clases y métodos  la cual la pasaremos al método IncludeXmlComments(). 

Ahora para activar la documentación en automático debemos especificarlo en el
archivo del proyecto (.csproj) de esta forma:

La etiqueta NoWarn nos servirá para que el sistema nos indique que otras clases  debemos documentar. 

Ahora el paso a seguir es agregar el pipeline del middleware, el cual se encargara  de regresar la información del servicio:

Por ultimo solo debemos realizar una petición a la ruta /swagger/api/swagger.json  y nos mostrara el esquema de nuestro servicio con la especificación OpenAPI.

Documentación en la web.

Para poder generar una página web con nuestra documentación eh incluso poder  realizar pruebas de nuestro servicio basta con hacer uso de Swagger UI. 

Para  realizar esto debemos ingresar el pipeline al middleware el cual nos generara  nuestra página web con la documentación:

En la llamada SwaggerEndpoint() debemos ingresar la ruta de nuestra petición
OpenAPI.

Ahora podemos sin problemas ir a nuestra ruta /swagger para poder visualizar la documentación interactiva de nuestra API. Esta nos mostrara bajo una sencilla interface toda la información de nuestra API y hasta podremos hacer test de la misma.

De esta manera tenemos una manera sencilla y rápida de realizar una
documentación de nuestro código.


Fuentes:

https://www.openapis.org/

https://swagger.io/