Spring Boot ❤️ Swagger
Hola querido lector o lectora,
Si el email anterior te gustó, has pasado la semana reflexionando sobre lo bien que vas a dejar documentados tus servicios REST y encima te quedaste a medias de todo el asunto….
Bueno pues hoy lo vamos a dejar zanjado, que no quiero volver a dejarte a medias, y te voy a explicar cómo tienes que montar Swagger en tu aplicación Spring Boot.
(Lo siento…. si estabas pensando en la documentación de tus servicios REST hechos con Node o Python… es otra ventanilla)
ADVERTENCIA: antes de nada tengo que avisarte que montar Swagger con Spring Boot es diferente para las versiones 2.X o 3.X. Pero no te preocupes que te explicaré ambas 😘.
Spring Boot 2.X
Añadimos la dependencia Springfox
En este punto ya tienes montada tu aplicación backend con Spring Boot 2.X y quieres dejar documentados tus servicios REST porque lo leíste en un post de un tío que sigues.
Pues lo “único” que tienes que haces es instalar la dependencia….
Springfox
¿Springfox?
Si si…. de hecho la dependencia se llama springfox-boot-starter.
¿Pero… no íbamos a utilizar swagger?
Bueno es que esta dependencia lo que va a hacer es transformar todo tu código y todas tus anotaciones en código de swagger.
¿Te acuerdas que en el email anterior decíamos que Swagger UI generaba todo el HTML a partir de un fichero JSON o YAML?
Bueno pues ese fichero lo genera esta dependencia!
De hecho como detallito te diré que esta dependencia realmente lo que hace es añadir estas otras 4 dependencias que son las que se encargan de hacer toda la magia:
Springfox-swagger2: añade todas las anotaciones para crear el documento JSON o YAML que es al equivalente al que hubiésemos generado con la herramienta de Swagger Editor.
Springfox-swagger-ui: dependencia que genera la web de Swagger UI a partir del JSON o YAML anterior.
Springfox-data-rest: hace que en el proceso de conversión de las anotaciones de Spring Boot a Swagger incluya también las anotaciones de Spring Data Rest.
Springfox-bean-validator: lo mismo que la anterior pero con las anotaciones de la dependencia de:
springboot-starter-validation.
Vale que si….. pero cómo instalo la dependencia?
Pues añadiendo lo siguiente en tu pom.xml
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>¿Cómo configurar Springfox?
Pues realmente como con la mayoría de dependencias starter de Spring boot que no necesitas hacer nada más, ya que a partir de todas las anotaciones de nuestros servicios REST (@RestController, @RequestMapping, @GetMapping, @PostMapping, etc…) va a montar la documentación.
Si aún así quieres tener tú el control de los detalles de lo que monta, porqué quieres ponerle una descripción bien rica a tu API o porqué quieres montar una validación por token. Entonces tendrás que crear un @Bean que devuelva un objeto Docket con la configuración que tú quieras.
Estos Beans te vienen añadidos en la dependencia no es que me los haya inventado 🤫.
¿Esto ha funcionado? ¿En serio?
Pues si, de hecho si vuelves a lanzar tu aplicación y abres la siguiente URL… (revisar el puerto y el path que estés usando en tu API)
http://localhost:8080/swagger-ui/Y si todo ha ido bien tendría que salir algo parecido a esto:
Spring Boot 3.X
Si tu caso es que estás usando una versión de Spring Boot 3.X y has leído todo lo anterior….. pues olvídalo. Y esto es porque Springfox NO es compatible con Spring Boot 3… oohh… pero hay otra librería que hace lo mismo…. BIEEEN!
Esta librería se llama: springdoc-openapi y hace lo mismo que Springfox.
Y es posible que te preguntes….
¿Y cómo es que hace lo mismo? ¿Por qué Springfox no da soporte a Spring Boot 3?
Pues porque se ha definido un estándar que se llama OpenAPI 3.0. Y lo que han hecho en este estándar es definir un patrón genérico para documentar cualquier API REST, de manera que gracias a este patrón haya más compatibilidad con más herramientas y no que cada herramienta tenga su patrón.
Entonces Spring ha creado esta dependencia más genérica.
Añadimos la dependencia Springdoc
Pues como cualquier dependencia.
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.6.0</version>
</dependency>
Cómo configurar Springfox
Realmente no tienes que configurar casi nada con estas dependencias, pero si a ti lo que te gusta es coger la sartén por el mango.
¿Esto ha funcionado? ¿En serio?
Y como antes ya estaría todo y si entramos en la siguiente URL veremos que bien nos ha quedado.
http://localhost:8080/swagger-ui/index.htmlSpringfox → SpringDoc Open Api
Si tú ya vas de avanzadillo de la clase y tienes toda tu API documentada PEEEERO la tienes con Spring Boot 2.X y Springfox y te estás planteando migrar a Spring Boot 3.X y SpringDoc…. pues para hacerte más fácil la migración te dejo este enlace:
https://springdoc.org/migrating-from-springfox.html
Referencias
Aquí te dejo enlaces de interés por si quieres ver más anotaciones, otros ejemplos y demás:
https://springfox.github.io/springfox/docs/current/#introduction
https://github.com/swagger-api/swagger-core/wiki/Annotations
Ya tienes todo el tutorial de cómo documentar tus servicios REST con Spring Boot y Swagger. Ahora te toca a ti pegarte con ello y adaptarlo a tus APIs.
Nos leemos la próxima semana!
Un saludo,