EN PROGRESO
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 versión y las dependencias:
<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>
NO SUBIR A GITLAB NUNCA, BAJO NINGÚN CONCEPTO, EL POM.XML CON LA DEPENDENCIA:
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
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