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. 

WADL: Que es y como generarlo

Este es el primer post tras el paso de Java EE a Jakarta EE en el nombre del blog. Por que como supongo que sabreis ya no es más Java EE ni depende de Oracle, sino que ahora es Jakarta EE, depende de la fundación Eclipse y han cambiado hasta el log. 

Como supongo que ya sabreis, cuando realizamos un servicio web tradicional con SOAP, a la vez debemos generar un contrato que indique como debemos utilizar el servicio. Este contrato es el WSDL. Y tal como habeis visto en los múltiples ejemplos de servicios web con REST que hemos realizado aquí, en principio nunca hemos hecho referencia de algo parecido, ni nos ha hecho falta para poder utilizarlos. 

Pero en los servicios REST también existe la posibilidad de crear este contrato. Lo podemos hacer con WSDL 2.0, y serán igual de enrevesados que los de SOAP, o bien podemos hacerlo con WADL. WADL, acrónimo de Web Application Description Language, es una forma más sencilla de generar este contrato en un formato XML, aunque aún no se encuentra estandarizado. Y en este post explicaremos como generarlo con Jersey.  

Basandonos en el ejemplo del post anterior, podemos ver como al arrancar el servicio podemos acceder al WADL que se ha generado automáticamente en la siguiente url: http://localhost:8080/JerseyExample/rest/application.wadl

Este WADL es generado en base a las anotaciones de Jax-RS y su estandar JSR-311. En base a esto, como Spring no implementa dicho estandar, no tiene una manera para generar automáticamente este WADL. Mirando por la web se podría hacer incluyendo implementaciones de dicho estandar en la aplicación Spring, pero no me parece la solución más optima.