Documentacion oficial: https://springdoc.org/
para que el proyecto pueda generar documentación swagger simplemente debemos inyectar la dependencia springdoc-openapi-ui
agregamos la librería en el archivo build.gradle:
Simplemente agregando la dependencia y ejecutando el proyecto podremos ver que spring doc hace una inspección de los controladores que están dentro del proyecto y nos genera documentación básica de los servicios.
Para ver la documentación nos dirigimos desde un navegador a: http://localhost:8080/swagger-ui/index.html
Como podemos ver tenemos una documentación muy básica de los servicios que nos detallan aspectos como:
- el método del servicio
- el path
- el body
- y el response.
También podremos observar que en la parte final de la página vemos una descripción de las entidades que están involucradas sobre los servicios:
A Pesar de que esto nos da una primera guia de como consumir los servicios es importante resaltar que la documentación es muy básica no nos da un contexto de qué significan los campos y qué valores concretos podemos ingresar.
Vamos a ver que podemos parametrizar para que la documentación sea más completa a la hora de ver la página de swagger.
Información general de la API:
En esta parte vamos a ver cómo parametrizar la información general de la API para que la podamos visualizar en swagger, esta información se compone de:
- título o nombre de la API
- descripción de lo que hace la API.
- Punto de contacto de soporte de la API
- servidores disponibles para hacer uso de la API
Los pasos a seguir para hacer esto son los siguientes:
- debemos agregar la información anteriormente descrita en nuestro archivo de configuracion application.yml, recomiendo que sea bajo esta estructura:
2. Luego dentro del paquete config vamos a crear una clase de configuración enfocada a parametrizar estos datos generales de Open API y la vamos a llamar OpenApiConfiguration y vamos a agregarle la anotación @Configuration
3. Luego vamos a agregar la anotación @OpenAPIDefinition por medio de esta anotación y la información que podemos inyectar vamos a ir asociando cada uno de los valores definidos en el archivo application.ym, el resultado esl:
4. Como podemos observar dentro de los nodos que ofrece la anotación OpenAPIDefinition vamos a ir referenciando la ubicación de la información del archivo .yml
5. si ejecutamos nuevamente la aplicación y volvemos a la página de swagger vamos a ver este resultado
Como podemos visualizar en la parte superior vemos la informaciónparametrizada en el application.yml
Información específica sobre cada controlador y sus operaciones:
Para detallar más que realiza cada controlador dentro de la aplicación y las operaciones que podemos hacer vamos a realizar los siguiente:
- sobre la clase PersonController vamos a agregar la anotación @Tag donde vamos a colocar un nombre para el controlador y una descripción:
2. Sobre cada método de operación del controlador vamos a agregar las anotaciones @Operation y @ApiResponses debe quedar de la siguiente manera:
3. La anotación @Operation nos va a servir para darle una descripción a que hace la función y la anotación @ApiResponse nos va a ayudar a describir lo que esperamos de la respuesta del servicio.
4. hacemos esto con cada servicio y ejecutamos nuevamente la aplicación y el resultado en swagger va a ser el siguiente:
5. Como podemos ver ya tenemos un nombre para el controlador y una descripción, como también una descripción para cada una de las operaciones.
6. También si entramos a alguna operación podremos ver el resultado que se espera:
Información específica sobre los tipos de error que puede presentarse en las operaciones:
Cuando agregamos la anotación @ResponseStatus sobre los métodos del exception handler, éstos también son tomados por swagger y son mostrados:
En la página de swagger se verá de la siguiente forma:
Información específica sobre cada entidad relacionada con los servicios:
Por medio de las anotaciones de swagger también es posible documentar cada una de las entidades que se relacionan dentro de los servicios que expone la aplicación.
Para esto vamos a ir a los modelos definidos en la capa de API en este caso Person:
por medio de la anotación @Schema vamos a definir el nombre de la entidad y también vamos a detallar cada uno de los atributos de la clase:
Definir nombre de entidad:
Describir cada uno de los atributos de la clase:
Podemos definir detalles como descripción del campo, ejemplo de uso y si es requerido o no
El resultado de hacer esto con cada entidad expuesta a nivel de servicio y dentro de la página de swagger es este:
En la parte de esquema vemos que va a salir el detalle que definimos en el modelo como si es requerido o no el ejemplo y la descripción.
También si vemos el detalle de alguno de los servicios nos vamos a dar cuenta de que el ejemplo de payload que nos aparece es el correspondiente a los ejemplos cargados dentro de modelo:
Lo cual va a facilitar el uso de la api para alguien que no sabe cómo hacerlo.
De esta manera la documentación de la API está dentro del código por lo que al momento de hacer cambios dentro de los contratos de la API va a ser mucho más sencillo mantener la documentación actualizada, diferente a lo que acostumbramos a hacer de tener documentos aparte e intentar tenerla actualizada cuando hacemos cambios de contrato. 👏 👏
