Swagger: Utilidad para desarrollar APIs

Ya estuvimos hablando en post anteriores sobre WADL. Ahora veremos Swagger, una alternativa para escribir un contrato de un servicio REST.

Swagger es un framework que nos permitirá según ellos mismos: diseñar, documentar, probar y desarrollar APIs. A continuación haremos un repaso de como nos ofrecen distintas herramientas para llevar a cabo esto mismo, pero solo hablaremos de las Open Source.

• Diseño

Para ello nos habilitan un editor YAML (que podemos descargar) para que nos ayude a definir como queremos que sea nuestra API: https://editor.swagger.io/. Este diseño de nuestra API, el cual podemos guardarlo en YAML o JSON, será de hecho un WADL pero con un formato propio de ellos. 

Aquí reside todo el peso a la hora de desarrollar nuestra API, puesto que por un lado tendremos que conocer la gramática para generar estos swagger correctamente. Y por otro lado, por que de no definirla bien, nuestra API no funcionará tal y como queremos. 

Si quieres saber más de como generar dicho fichero deberás ir a la doc y empapartela un poquito. 

• Documentación

Para la documentación nos habilitan una solución similar a la anterior, el Swagger UI. También podremos bajarlo y nos permitirá ver en un aspecto más visual del fichero anteriormente creado. Aquí veremos las APIs que tenemos, los parámetros de entrada que tienen, el retorno que devuelven y las posibles excepciones. Todo ello siempre y cuando lo hayamos configurado en el paso anterior, repito.

• Test

A través del Swagger UI, también podremos realizar llamadas de prueba a dicho servicio, a través de un botón disponible en cada una de las descripciones de las APIs. 

• Desarrollo

Como parte del mismo editor que hemos visto en el punto uno, podemos además generar un servidor y cliente de forma automática en multiples lenguajes. Lo que obviamente nos ahorraría muchisimos trabajo.

Aquí puedes ver un ejemplo de como serían estos ficheros de diseño de API de un antiguo ejemplo de REST API con Spring Boot.