Historial de página

...

1. Configuración

<properties>
...
<springdoc.version>1.6.

12</springdoc.version>
...
</properties

<!-- API DOC -->
<dependency>
	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-webmvc-core</artifactId>
	<version>${springdoc.version}</version>
</dependency>

<dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-hateoas</artifactId>
      <version>${springdoc.version}</version>
</dependency>

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-data-rest</artifactId>
    <version>${springdoc.version}</version>
</dependency>

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-security</artifactId>
    <version>${springdoc.version}</version>
</dependency>

# SpringDoc OpenAPI Documentation
springdoc.api-docs.path=/api-docs
# Propiedades inventadas para reubicar las peticiones
springdoc.server.url=https://apidesa.um.es
springdoc.server.path=/${app.author}/${app.apiname}
springdoc.security.issuer-uri=${cas.url}/cas/oidc 

...

2. Documentar servicios

Para documentar correctamente nuestros servicios, SpringDoc/Swagger ofrece varias anotaciones, tanto a nivel de clase como de método:

...

@GetMapping( "/misdtos" )
public ResponseEntity<PagedModel<MiDTORepresentationModel>> misdtos(@ParameterObject @PageableDefault( size = 50) Pageable pageable) {

• ¿Cómo puedo ver en local la documentación OpenAPI?

Para poder ver, en mi entorno local, cómo quedaría mi documentación OpenApi, no necesito añadir ninguna dependencia extra para levantar un frontal web que la lea. Por defecto, en las aplicaciones FundewebJS, el JSON que representa la documentación OpenAPI se encuentra en http://localhost:8080/api-docs.

Por tanto lo que tenemos que hacer es, acceder a esa URL y copiar el JSON resultante. Una vez copiado nos vamos a Swagger.io https://editor-next.swagger.io/ y pegamos en la parte izquierda nuestro JSON (deberemos quitar todos los comentarios "//" ya que de lo contrario no leerá bien el formato).

Una vez pegado, en la parte de la derecha veremos nuestra documentación en formato web.

...

Referencias

• Documentación SpringDoc OpenApi: https://springdoc.org/#Introduction
• Notaciones Swagger: https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations
• Baeldung SpringDoc OpenApi: https://www.baeldung.com/spring-rest-openapi-documentation
• Set List of Objects in Swagger API Response: https://www.baeldung.com/java-swagger-set-list-response

...