En esta página se describirá cómo configurar las aplicaciones Spring-Boot para generar la documentación usada en api.um.es

Para realizar esta documentación se utilizará la librería OpenApi.

Guía detallada

Cambios a realizar:

 1. pom.xml

Añadir la dependencia:

<properties>
...
<springdoc.version>1.5.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>

2. application.properties

Estas variables se incluyen para la configuración local, por si se quisiera realizar alguna comprobación levantando swagger-ui, pero ya estará configurada en los entornos. NO HACE FALTA PARA LOS ENTORNOS. 
Preguntar a MNCS ante cualquier duda.

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

Las propiedades:

• app.author
• app.apiname
• cas.url

Deben estar declaradas previamente siguiendo la página de confluence: Migración del backend a soporte oAuth.

3. Documentar servicio

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

    3.1 Anotaciones de clase

@OpenAPIDefinition (
    info = @Info(title = "TITULO DE LA APLICACIÓN", version = "${server.image:0.0.0}", description = "DESCRIPCIÓN DEL API."), servers = {
	@Server( url = "${springdoc.server.url}" )
} )
@SecurityScheme(	name = "OIDC",
					type = SecuritySchemeType.OPENIDCONNECT,
					openIdConnectUrl = "${springdoc.security.issuer-uri}/.well-known/openid-configuration" )

            De este código, modificar únicamente los atributos:

• title => Título que se mostrará en la documentación. Si tenemos varias clases según los recursos (como debería ser), mencionar en este title el recurso con el que se trabaja en la clase.
               P.Ej.: "Consulta de Expediente Académico", "Consulta de Datos de Afiliación", "Solicitudes de Matrícula".
• description => Descripción larga genérica de los endpoints expuestos en la clase.

      3.2 Anotaciones de método

 @Operation(summary = "TITULO DEL ENDPOINT", 
            description = "DESCRIPCION DEL ENDPOINT.",
            tags = {""}, //TAG PARA AGRUPAR EN LA DOCUMENTACIÓN
            responses = { 
                 @ApiResponse(responseCode = "500", description=""), 
                 @ApiResponse(responseCode = "200", 
                            description="DESCRIPCION DE LA RESPUESTA SEGÚN EL CÓDIGO DEVUELTO",
                            content= @Content(schema=@Schema(implementation=ClaseDTODevuelto.class))) 
                .... 
            })

De este código los atributos a configurar serían:

• summary => Título, resumen descriptivo del endpoint.
• description => Descripción larga del endpoint.
• tags => Listado de tags para agrupar endpoints en la documentación. Se recomienda usar solo, de momento, "Public" o "Private" según el ámbito de nuestro endpoint.
• responses => Listado de códigos de respuesta devueltos por el endpoint. 
                       Rellenar, según el caso:
  • • • responseCode => código de respuesta http
      • description => descripción de la casuística cuando se devuelve el código de respuesta
      • content => clase devuelta cuando sucede la respuesta, por ejemplo, un DTO devuelto. (No incluir en caso de error o desconocimiento, es opcional).

Se recomienda que los servicios controlen y devuelvan un conjunto de respuestas completos, según las posibles casuísticas de éxito y error. Ver => Manejo de Errores en FundeWebJS.

Referencias

• Documentación SpringDoc OpenApi: https://springdoc.org/#Introduction
• Notaciones Swagger: https://github.com/swagger-api/swagger-core/wiki/Annotations
• Baeldung SpringDoc OpenApi: https://www.baeldung.com/spring-rest-openapi-documentation

Artículos Relacionados

Aquí aparecen artículos relacionados sobre la base de las etiquetas que usted seleccione. Haga clic para editar la macro y añadir o modificar las etiquetas.