SpringDoc es un componente de Spring Boot que simplifica la generación y mantenimiento de documentación. Esta basado en la especificación OpenAPI 3 (en las versiones de Spring Boot 3.x). Además integra Swagger para dotar de una interfaz gráfica que documenta y permite probar la API.

Dependencia

La dependencia de SpringDoc es la siguiente:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version>
</dependency>

Nota: para Spring Boot 3.x hay que utilizar la versión 2 (o superior) de springdoc-openapi

Configuración

Se pueden customizar algunos parámetros desde el properties de la aplicación, por ejemplo:

URL para la especificación de la API en formato JSON

springdoc.api-docs.path=/api/v1/api-spec

URL para la interfaz gráfica de swagger

springdoc.swagger-ui.path=/api/v1/api-gui.html

Orden por defecto en el que aparecerán las operaciones/métodos

springdoc.swagger-ui.operationsSorter=method

En la clase principal del proyecto, se puede incorporar, mediante la anotación @OpenApiDefinition, la información general de la API. Por ejemplo:

@OpenAPIDefinition(
  info =@Info(
    title = "Blog API",
    version = "v1",
    contact = @Contact(
      name = "Daniel Garcia Costa", email = "daniel.garcia@uv.es", url = "garcosda.uv.es"
    ),
    license = @License(
      name = "Apache 2.0", url = "https://www.apache.org/licenses/LICENSE-2.0"
    ),
    description = "This is a simple blog application"
  ),
  servers = @Server(
    url = "/",
    description = "Production"
  )
)

Además, a nivel de endpoint, se puede añadir información que ayude a generar una documentación más clara.

Por un lado información general sobre el endpoint.

@Operation(summary="Find Posts", description="Find posts by ID")

Y por otro lado, información específica sobre las respuestas del endpoint

@ApiResponses(value = { 
    @ApiResponse(responseCode = "200", description = "Found the post", 
    content = { @Content(mediaType = "application/json", 
      schema = @Schema(implementation = Post.class)) }),
    @ApiResponse(responseCode = "400", description = "Invalid id supplied", 
    content = @Content), 
    @ApiResponse(responseCode = "404", description = "Post not found", 
    content = @Content) })

También se puede añadir información a los objectos de dominio, DTOs o cualquier otro objecto que se transfiera mediante la anotación @Schema.

@Schema(description = "Post content")

Acceso a la información generada por SpringDoc

Con el proyecto ejecutado, se puede consultar la especificación de la API en http://127.0.0.1:8080/api/v1/api-spec

Y la interfaz de Swagger en http://127.0.0.1:8080/api/v1/api-gui.html

Generar PDF

SpringDoc no permite generar un PDF a partir de la especificación. Aunque se puede hacer integrando diferentes dependencias (json a markdown y markdown a PDF), existen herramientas online que lo hacen, por ejemplo, https://www.swdoc.org/