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 dependencia:
<!-- API DOC --> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-webmvc-core</artifactId> <version>1.5.12</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"
)
3.2 Anotaciones de método
@Operation(summary = "TITULO DEL ENDPOINT",
description = "DESCRIPCION DEL ENDPOINT.",
tags = {"Public"}, //TAG PARA AGRUPAR EN LA DOCUMENTACIÓN
responses = {
@ApiResponse(responseCode = "200", //CODIGO DE RESPUESTA
description="DESCRIPCION DE LA RESPUESTA SEGÚN EL CÓDIGO DEVUELTO",
content= @Content(schema=@Schema(implementation=GithubUser.class))) //CONTENIDO DE LA RESPUESTA SEGÚN EL CÓDIGO DEVUELTO
.... Incluir todos los ApiResponse necesarios.
})