Swagger: más comodidad en el desarrollo de API

En los proyectos de desarrollo, la documentación conlleva mucho tiempo, y las personas externas suelen desconocer los beneficios que puede aportar al mantenimiento y el desarrollo continuo de sistemas. A más tardar uno se da cuenta de esto cuando dichas tareas no son realizadas por el equipo que ha desarrollado el sistema, lo que tiende a ser más la norma que la excepción.

Todavía más importante es la documentación de las API, es decir, de las application programming interfaces o, en español, interfaces de programación de aplicaciones. Estas conectan aplicaciones entre sí, y las propias aplicaciones con fuentes de datos y otros sistemas. En la actualidad, apenas se dan escenarios de aplicación en los que un conjunto variado de API no tenga un papel importante en las conexiones de software. Pero, para poder utilizar las interfaces, también hay que conocer su estructura y funciones. La especificación OpenAPI Swagger hace esto posible, pues, al ser un formato de código abierto, ayuda a mantener el control sobre las diferentes capacidades de las API. Con Swagger también es posible que las personas no involucradas directamente en el proceso de desarrollo faciliten API: ven las interfaces utilizadas y pueden documentarlas.

Debido al amplio abanico de tecnologías y lenguajes de programación, describir las API era una tarea muy compleja en el pasado. Un primer punto importante: para el desarrollo de las API, actualmente se utiliza el paradigma de programación REST. Sitios web como Google, Amazon y Twitter utilizan API de RESTful. Anteriormente se describían las interfaces en el lenguaje de descripción de servicios web WSDL. Desde el punto de vista técnico, con WSDL 2.0 también se pueden describir API de REST, lo que es muy complicado para los desarrolladores. El lenguaje de descripción de aplicaciones web (WADL) debía solucionar este problema, pero nunca pudo llegar a estandarizarse por su estructura XML.

Por eso, Swagger se ha convertido en poco tiempo en la tecnología más popular para las documentaciones de API. Mejor dicho, en la tecnología más popular para las API de REST utilizadas con más frecuencia. Swagger fue desarrollado por Reverb, pero actualmente se caracteriza por su neutralidad como código abierto al abrigo de la Fundación Linux, llamada Open API Initiative. Con el tiempo, Swagger se ha renombrado como especificación OpenAPI, aunque sigue siendo conocido de manera no oficial con el nombre de Swagger.

En una ponencia de la API Conference, se presentó Swagger como ejemplo de Spring Boot, entre otros, y se explicó su integración en la rutina.

Dependiendo del ámbito de aplicación, el elemento principal de Swagger es un archivo JSON o YAML. La interfaz de usuario con la que se pueden crear documentaciones fácilmente está basada en HTML y JavaScript. Básicamente, Swagger tiene un formato de lenguaje neutral y legible por máquina. A través de la interfaz de usuario no solo se puede gestionar la documentación, sino que Swagger también puede realizar pruebas ad hoc, por ejemplo.

Otra ventaja de Swagger se hace patente en la posibilidad de desarrollo gracias a la compatibilidad con la librería central, Swagger Core. Se complementa con la interfaz de usuario llamada Swagger UI, el generador de código Swagger Codegen y el Swagger Editor.

Pero, si por algo destaca Swagger, al igual que otras opciones de código abierto, es su relación con el amplio ecosistema de GitHub. Los desarrolladores encuentran aquí generadores de código para casi todos los lenguajes de programación. Swagger documenta cada interfaz con toda la información.

El archivo de la documentación comienza con la indicación de la versión de especificación empleada. Después, siguen los datos generales sobre la API clasificados de manera clara en la categoría “info”. Swagger también disgrega el alojamiento, la ruta y el esquema URL y los especifica individualmente. Ya después vienen el tipo de medio para toda la API. Este procedimiento funciona como un complejo sistema de fichas.

Una vez finalizada la categorización, se presenta el contenido: rutas, operadores y parámetros se procesan junto con la descripción correspondiente. Los tipos de datos se gestionan cada uno en su sección. Con Swagger UI se puede visualizar el conjunto no solo en forma textual, sino también gráficamente. Esto supone una ventaja sobre todo si se tienen que enviar solicitudes de prueba directamente desde el navegador. Esta combinación de documentación perfecta y posibilidad de envío directo de solicitudes API es lo que hace a Swagger tan valioso.

Para el desarrollo de API es esencial contar con una documentación ordenada y comprensible, pues solo así pueden utilizarse las interfaces de los desarrolladores. Esto es aún más importante para las API públicas: sin documentación, estas son inservibles para la comunidad, no se pueden divulgar y no traen éxito.

En estos momentos, Swagger es la mejor opción para documentar API de REST, porque puede representar casi todos los servicios web y la información en torno a la interfaz. Crece al mismo ritmo que el sistema y documenta los cambios automáticamente. El funcionamiento no acarrea problemas, porque Swagger deposita la documentación de la API de REST directamente en el código.

El punto de partida de cualquier desarrollo API es o bien el código de programa (Code First) o la descripción de la interfaz (Design First). Si hablamos de un desarrollo que sigue la máxima Code First, el punto de partida establecido es el código de programa. A partir de este, Swagger puede deducir directamente una documentación independiente del lenguaje de programación utilizado y legible tanto por máquinas como por seres humanos.

Por el otro lado, está el paradigma Design First. Como ya hemos mencionado, diferentes desarrolladores son responsables de un cliente y un servidor. En el paradigma Design First se finaliza primero la descripción y, a continuación, se generan los códigos fácilmente con Swagger. Para ello hay generadores para todos los lenguajes de programación habituales e incluso plantillas que se pueden adaptar o ampliar.

Swagger ofrece casi de manera automática un código API coherente. Si algo no cuadra en la programación manual, aparecen errores de compilación visibles automáticamente en un sistema de integración continua.

Sus ventajas predominan de tal manera que Swagger puede definirse como la aplicación estándar por excelencia para la descripción de interfaces en las API de RESTful. Como otras tantas aplicaciones de código abierto, Swagger disfruta de una gran divulgación y, con ello, de compatibilidad con muchas herramientas. El gremio de Swagger está formado por grandes de la tecnología como Microsoft, IBM y Google, con lo que la especificación OpenAPI cuenta con respaldo incondicional, aunque haya alternativas como Restful API Modelling Language (RAML). Este también se basa en YAML y desarrolla definiciones todavía más complejas que Swagger, pero incluso su creador (Mulesoft) ha entrado a formar parte de la OpenAPI Initiative.

Una pequeña desventaja de Swagger es la comprensión y legibilidad de la documentación. Aunque Swagger ofrece un formato relativamente bien elaborado, se requiere un tiempo para familiarizarse con él. Una prueba de que puede ser más sencillo es la API Blueprint, con su sintaxis de Markdown.

En la página web de Swagger UI se encuentra el paquete comprimido completo (formato ZIP). Una vez descargado, hay que decidir si ejecutar Swagger localmente o en un servidor.

Atención: si quieres que funcione localmente, se necesita MAMP. La carpeta descomprimida Swagger UI Master se guarda en el directorio MAMP o en el servidor. Ahora solo se necesita acceder al URL del servidor o al alojamiento local en el navegador para que Swagger se abra automáticamente y la primera documentación API se inicie.

Con la versión web del Swagger Editor es todavía más fácil. Este se puede ejecutar sin problema en el navegador y tiene como ventaja que, además del editor de texto, se puede visualizar una versión gráfica de la documentación.

En este extracto de un ejemplo de Swagger, ya se puede reconocer la estructura inteligible. Toda la información se menciona claramente y puede ser comprendida independientemente del lenguaje de programación.

A continuación, se puede exportar la documentación directamente como archivo YAML o convertirla primero en formato JSON. Este es el archivo de documentación que Swagger UI puede leer. Los contenidos mostrados indican en primer lugar las rutas, las interfaces y los puntos finales. Después es el turno de las descripciones, los parámetros y la respuesta y sus significados. En los terminales pueden ejecutarse pruebas ad hoc a través de la interfaz de usuario de Swagger.

Lo bueno del código abierto es que se pueden probar herramientas de manera gratuita. Este es el caso de Swagger para la interfaz de usuario y también para todas las herramientas. De esta manera, uno puede hacerse una idea de las posibilidades que ofrece Swagger.