Documentar API REST con Spring Doc (Swagger)

 

Configuración del Proyecto

Primero se obtiene última versión disponible de Spring Boot 

Agregamos la dependencia de https://springdoc.org/ en nuestro pom.xml

Con nuestro proyecto ya creado creamos el siguiente controller (El service , repository y entity son un CRUD basico):

@RestController

@RequestMapping("/")

public class PersonaController {

protected PersonService personService;

public PersonaController(PersonService personService) {

super();

this.personService = personService;

}

@PostMapping

    public ResponseEntity<Person> addPersona(@RequestBody Person persona) {

personService.addPersona(persona);

        return new ResponseEntity<>(persona, HttpStatus.CREATED);

    }

    @GetMapping

    public ResponseEntity<List<Person>> getAllPersonas() {

        return new ResponseEntity<>(personService.getAllPersonas(), HttpStatus.OK);

    }

    @GetMapping("/{id}")

    public ResponseEntity<Person> getPersona(@PathVariable Integer id) {

        Optional<Person> person = personService.getPersona(id);

        

        if(person.isEmpty()) {

         return ResponseEntity.ok(null);

        }

        

        return ResponseEntity.ok(person.get());

        

    }

}

 

Con estas simples configuraciones de forma automatica spring doc genera una documentación en nuestro controlador , basándose en las anotaciones de Spring Boot.

Documentación de la Información del Proyecto

Es común que en nuestra api tengamos la necesidad de personalizar el título , versión , entre otras cosas . Esto lo podemos hacer mediante el uso de etiquetas de la siguiente manera : 

Aquí notamos que algunas opciones configurables son : 

• Título del proyecto 

• Descripción 

• Version 

• Términos de servicio

• Contacto 

• Servidores

Con estos cambios aplicados al refrescar la url del swagger obtenemos el siguiente resultado

Autenticacion 

La mayoría de las veces los servicios cuentan con algún método de autenticación  como puede ser  el envío de un token. 

Para agregar esto se realiza con la etiqueta @SecurityScheme

Nótese que el valor del atributo name de la anotación Security Scheme se agrega en el apartado de Security Requirement.

Ahora si al actualizar el api ya podremos ver que es posible agregar el token de autenticación para nuestras api.

Es importante comentar que el estándar open api soporta diferentes tipos de autenticación. 

Para mayor información sobre los distintos tipos de autenticación soportados recomiendo  ver el apartado Autenticación en el estándar.  

 

Documentación de Servicios 

Aunque con el simple hecho de agregar la dependencia de spring-doc obtenemos  documentación automatizada , de igual forma  es posible detallarlas mediante etiquetas propias de open-api / swagger. Algunas de ellas son : 

• @Operation: Describe una operación o endpoint específico.

• @Parameter: Detalla los parámetros de la operación.

• @Schema: Describe un modelo de datos.

• @ApiResponse: Documenta las posibles respuestas de un endpoint.

Un ejemplo de uso es el siguiente : 

Al refrescar nuestro swagger ya es posible ver los cambios en el navegador

Ocultar Atributos

Por experiencia propia algunas ocasiones existen atributos en los DTO 's que nos gustaría que no se vieran para nuestros consumidores, en estos escenarios podemos utilizar la etiqueta @Hidden .

Uso en Clases Genéricas

Otro de los escenarios a los cuales nos enfrentamos es cuando diseñamos clases genéricas ya que debido a sus múltiples implementaciones  pudiéramos tener dudas al saber cómo documentarlo . 

La primera recomendación es leer primero el  apartado de Describing Responses.el cual nos ayudará a saber cómo spring-doc utiliza los esquemas . 

Una vez entendido que es un esquema veamos el siguiente ejemplo con un controlador de una consulta paginada . 

Al momento de actualizar la documentación se puede observar ambas implementaciones correctamente documentadas . 

Aquí notamos que el buen diseño en las clases es un factor importante para facilitar la documentación en automático.

De igual manera no importa si en nuestro servicio con clases genéricas tenemos múltiples respuestas de códigos http también es posible realizarlo agregando las etiquetas antes vistas .

Customizar programaticamente Open API 

Debido al reuso de los DTO 's entre varios servicios en ocasiones sentimos la necesidad de adecuar de manera personalizada un controlador  en nuestra api .

Para esos casos podemos utilizar la clase OpenApiCustomizer , el cual puede ser utilizada en los siguientes casos  :

 

• Información General de la API: Modificar el título, descripción, términos de servicio, contacto y otra información general de la API.

• Paths: Modificar, agregar o eliminar endpoints y sus operaciones.

• Schemas: Definir o modificar los esquemas de datos utilizados en la API.

• Security: Configurar esquemas de seguridad, como OAuth2, API keys, etc.

• Responses: Personalizar las respuestas de los endpoints, incluyendo ejemplos y descripciones detalladas.

• Request Bodies: Modificar o definir los cuerpos de las solicitudes.

Un ejemplo de cómo podríamos documentar el servicio de forma customizada con OpenApiCustomizer de springdoc es el siguiente : 

Es necesario mencionar que dicha clase hay que registrarla como un Bean.  

Por último al actualizar la documentación podemos ver los cambios realizados .

Conclusiones 

Como pudimos observar con spring doc tenemos las siguientes ventajas :  

• Automatización : Ya que genera la documentación del api basándose en las anotaciones de Spring y el código del Controlador , por lo que es altamente recomendable favorecer un buen diseño y tener buenas prácticas al programar.

• Soporte con Anotaciones : Usa las anotaciones estándar de Spring (como @RestController, @RequestMapping, @GetMapping, etc.) y ademas provee de  extensiones provenientes de  OpenAPI/Swagger (como @Operation, @ApiResponse, etc.) para generar documentación precisa y detallada. 

• OpenApiCustomizer: Permite personalizar la documentación generada ajustando la configuración del objeto OpenAPI después de que se haya generado automáticamente. Esto es útil para agregar detalles específicos que no se pueden definir directamente mediante anotaciones.

Finalmente me queda claro hay más escenarios los cuales no cubri por eso les comparto la documentación de spring doc  : 

https://springdoc.org/

Al igual que el repositorio de código con los ejemplos vistos en este breve tutorial : 

https://github.com/juanrenatonoh/springdoc-con-springboot