Swagger: más comodidad en el de­sa­rro­llo de API

En los proyectos de de­sa­rro­llo, la do­cu­me­n­ta­ción conlleva mucho tiempo, y las personas externas suelen de­s­co­no­cer los be­ne­fi­cios que puede aportar al ma­n­te­ni­mie­n­to y el de­sa­rro­llo continuo de sistemas. A más tardar uno se da cuenta de esto cuando dichas tareas no son rea­li­za­das por el equipo que ha de­sa­rro­lla­do el sistema, lo que tiende a ser más la norma que la excepción.

Todavía más im­po­r­ta­n­te es la do­cu­me­n­ta­ción de las API, es decir, de las ap­pli­ca­tion pro­gra­m­mi­ng in­te­r­fa­ces o, en español, in­te­r­fa­ces de pro­gra­ma­ción de apli­ca­cio­nes. Estas conectan apli­ca­cio­nes entre sí, y las propias apli­ca­cio­nes con fuentes de datos y otros sistemas. En la ac­tua­li­dad, apenas se dan es­ce­na­rios de apli­ca­ción en los que un conjunto variado de API no tenga un papel im­po­r­ta­n­te en las co­ne­xio­nes de software. Pero, para poder utilizar las in­te­r­fa­ces, también hay que conocer su es­tru­c­tu­ra y funciones. La es­pe­ci­fi­ca­ción OpenAPI Swagger hace esto posible, pues, al ser un formato de código abierto, ayuda a mantener el control sobre las di­fe­re­n­tes ca­pa­ci­da­des de las API. Con Swagger también es posible que las personas no in­vo­lu­cra­das di­re­c­ta­me­n­te en el proceso de de­sa­rro­llo faciliten API: ven las in­te­r­fa­ces uti­li­za­das y pueden do­cu­me­n­tar­las.

Debido al amplio abanico de te­c­no­lo­gías y lenguajes de pro­gra­ma­ción, describir las API era una tarea muy compleja en el pasado. Un primer punto im­po­r­ta­n­te: para el de­sa­rro­llo de las API, ac­tua­l­me­n­te se utiliza el paradigma de pro­gra­ma­ción REST. Sitios web como Google, Amazon y Twitter utilizan API de RESTful. An­te­rio­r­me­n­te se de­s­cri­bían las in­te­r­fa­ces en el lenguaje de de­s­cri­p­ció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 co­m­pli­ca­do para los de­sa­rro­lla­do­res. El lenguaje de de­s­cri­p­ción de apli­ca­cio­nes web (WADL) debía so­lu­cio­nar este problema, pero nunca pudo llegar a es­ta­n­da­ri­zar­se por su es­tru­c­tu­ra XML.

Por eso, Swagger se ha co­n­ve­r­ti­do en poco tiempo en la te­c­no­lo­gía más popular para las do­cu­me­n­ta­cio­nes de API. Mejor dicho, en la te­c­no­lo­gía más popular para las API de REST uti­li­za­das con más fre­cue­n­cia. Swagger fue de­sa­rro­lla­do por Reverb, pero ac­tua­l­me­n­te se ca­ra­c­te­ri­za por su neu­tra­li­dad como código abierto al abrigo de la Fundación Linux, llamada Open API Ini­tia­ti­ve. Con el tiempo, Swagger se ha re­no­m­bra­do como es­pe­ci­fi­ca­ción OpenAPI, aunque sigue siendo conocido de manera no oficial con el nombre de Swagger.

En una ponencia de la API Co­n­fe­re­n­ce, se presentó Swagger como ejemplo de Spring Boot, entre otros, y se explicó su in­te­gra­ción en la rutina.

De­pe­n­die­n­do del ámbito de apli­ca­ción, el elemento principal de Swagger es un archivo JSON o YAML. La interfaz de usuario con la que se pueden crear do­cu­me­n­ta­cio­nes fá­ci­l­me­n­te está basada en HTML y Ja­va­S­cri­pt. Bá­si­ca­me­n­te, 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 do­cu­me­n­ta­ción, sino que Swagger también puede realizar pruebas ad hoc, por ejemplo.

Otra ventaja de Swagger se hace patente en la po­si­bi­li­dad de de­sa­rro­llo gracias a la co­m­pa­ti­bi­li­dad con la librería central, Swagger Core. Se co­m­ple­me­n­ta 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 eco­si­s­te­ma de GitHub. Los de­sa­rro­lla­do­res en­cue­n­tran aquí ge­ne­ra­do­res de código para casi todos los lenguajes de pro­gra­ma­ción. Swagger documenta cada interfaz con toda la in­fo­r­ma­ción.

El archivo de la do­cu­me­n­ta­ción comienza con la in­di­ca­ción de la versión de es­pe­ci­fi­ca­ción empleada. Después, siguen los datos generales sobre la API cla­si­fi­ca­dos de manera clara en la categoría “info”. Swagger también disgrega el alo­ja­mie­n­to, la ruta y el esquema URL y los es­pe­ci­fi­ca in­di­vi­dua­l­me­n­te. Ya después vienen el tipo de medio para toda la API. Este pro­ce­di­mie­n­to funciona como un complejo sistema de fichas.

Una vez fi­na­li­za­da la ca­te­go­ri­za­ción, se presenta el contenido: rutas, ope­ra­do­res y pa­rá­me­tros se procesan junto con la de­s­cri­p­ción co­rre­s­po­n­die­n­te. Los tipos de datos se gestionan cada uno en su sección. Con Swagger UI se puede vi­sua­li­zar el conjunto no solo en forma textual, sino también grá­fi­ca­me­n­te. Esto supone una ventaja sobre todo si se tienen que enviar so­li­ci­tu­des de prueba di­re­c­ta­me­n­te desde el navegador. Esta co­m­bi­na­ción de do­cu­me­n­ta­ción perfecta y po­si­bi­li­dad de envío directo de so­li­ci­tu­des API es lo que hace a Swagger tan valioso.

Para el de­sa­rro­llo de API es esencial contar con una do­cu­me­n­ta­ción ordenada y co­m­pre­n­si­ble, pues solo así pueden uti­li­zar­se las in­te­r­fa­ces de los de­sa­rro­lla­do­res. Esto es aún más im­po­r­ta­n­te para las API públicas: sin do­cu­me­n­ta­ción, estas son in­se­r­vi­bles para la comunidad, no se pueden divulgar y no traen éxito.

En estos momentos, Swagger es la mejor opción para do­cu­me­n­tar API de REST, porque puede re­pre­se­n­tar casi todos los servicios web y la in­fo­r­ma­ción en torno a la interfaz. Crece al mismo ritmo que el sistema y documenta los cambios au­to­má­ti­ca­me­n­te. El fu­n­cio­na­mie­n­to no acarrea problemas, porque Swagger deposita la do­cu­me­n­ta­ción de la API de REST di­re­c­ta­me­n­te en el código.

El punto de partida de cualquier de­sa­rro­llo API es o bien el código de programa (Code First) o la de­s­cri­p­ción de la interfaz (Design First). Si hablamos de un de­sa­rro­llo que sigue la máxima Code First, el punto de partida es­ta­ble­ci­do es el código de programa. A partir de este, Swagger puede deducir di­re­c­ta­me­n­te una do­cu­me­n­ta­ción in­de­pe­n­die­n­te del lenguaje de pro­gra­ma­ción utilizado y legible tanto por máquinas como por seres humanos.

Por el otro lado, está el paradigma Design First. Como ya hemos me­n­cio­na­do, di­fe­re­n­tes de­sa­rro­lla­do­res son re­s­po­n­sa­bles de un cliente y un servidor. En el paradigma Design First se finaliza primero la de­s­cri­p­ción y, a co­n­ti­nua­ción, se generan los códigos fá­ci­l­me­n­te con Swagger. Para ello hay ge­ne­ra­do­res para todos los lenguajes de pro­gra­ma­ción ha­bi­tua­les e incluso pla­n­ti­llas que se pueden adaptar o ampliar.

Swagger ofrece casi de manera au­to­má­ti­ca un código API coherente. Si algo no cuadra en la pro­gra­ma­ción manual, aparecen errores de co­m­pi­la­ción visibles au­to­má­ti­ca­me­n­te en un sistema de in­te­gra­ción continua.

Sus ventajas pre­do­mi­nan de tal manera que Swagger puede definirse como la apli­ca­ción estándar por ex­ce­le­n­cia para la de­s­cri­p­ción de in­te­r­fa­ces en las API de RESTful. Como otras tantas apli­ca­cio­nes de código abierto, Swagger disfruta de una gran di­vu­l­ga­ción y, con ello, de co­m­pa­ti­bi­li­dad con muchas he­rra­mie­n­tas. El gremio de Swagger está formado por grandes de la te­c­no­lo­gía como Microsoft, IBM y Google, con lo que la es­pe­ci­fi­ca­ción OpenAPI cuenta con respaldo in­co­n­di­cio­nal, aunque haya al­te­r­na­ti­vas como Restful API Modelling Language (RAML). Este también se basa en YAML y de­sa­rro­lla de­fi­ni­cio­nes todavía más complejas que Swagger, pero incluso su creador (Mulesoft) ha entrado a formar parte de la OpenAPI Ini­tia­ti­ve.

Una pequeña de­s­ve­n­ta­ja de Swagger es la co­m­pre­n­sión y le­gi­bi­li­dad de la do­cu­me­n­ta­ción. Aunque Swagger ofrece un formato re­la­ti­va­me­n­te bien elaborado, se requiere un tiempo para fa­mi­lia­ri­zar­se 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 co­m­pri­mi­do completo (formato ZIP). Una vez de­s­ca­r­ga­do, hay que decidir si ejecutar Swagger lo­ca­l­me­n­te o en un servidor.

Atención: si quieres que funcione lo­ca­l­me­n­te, se necesita MAMP. La carpeta de­s­co­m­pri­mi­da Swagger UI Master se guarda en el di­re­c­to­rio MAMP o en el servidor. Ahora solo se necesita acceder al URL del servidor o al alo­ja­mie­n­to local en el navegador para que Swagger se abra au­to­má­ti­ca­me­n­te y la primera do­cu­me­n­ta­ció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 vi­sua­li­zar una versión gráfica de la do­cu­me­n­ta­ción.

En este extracto de un ejemplo de Swagger, ya se puede reconocer la es­tru­c­tu­ra in­te­li­gi­ble. Toda la in­fo­r­ma­ción se menciona cla­ra­me­n­te y puede ser co­m­pre­n­di­da in­de­pe­n­die­n­te­me­n­te del lenguaje de pro­gra­ma­ción.

A co­n­ti­nua­ción, se puede exportar la do­cu­me­n­ta­ción di­re­c­ta­me­n­te como archivo YAML o co­n­ve­r­ti­r­la primero en formato JSON. Este es el archivo de do­cu­me­n­ta­ción que Swagger UI puede leer. Los co­n­te­ni­dos mostrados indican en primer lugar las rutas, las in­te­r­fa­ces y los puntos finales. Después es el turno de las de­s­cri­p­cio­nes, los pa­rá­me­tros y la respuesta y sus si­g­ni­fi­ca­dos. En los te­r­mi­na­les pueden eje­cu­tar­se pruebas ad hoc a través de la interfaz de usuario de Swagger.

Lo bueno del código abierto es que se pueden probar he­rra­mie­n­tas de manera gratuita. Este es el caso de Swagger para la interfaz de usuario y también para todas las he­rra­mie­n­tas. De esta manera, uno puede hacerse una idea de las po­si­bi­li­da­des que ofrece Swagger.