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.
Cambios a realizar:
Añadir la dependencia:
<!-- API DOC --> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-webmvc-core</artifactId> <version>1.5.12</version> </dependency> |
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:
Deben estar declaradas previamente siguiendo la página de confluence: Migración del backend a soporte oAuth.
Para documentar correctamente nuestros servicios, OpenAPI ofrece varias anotaciones, tanto a nivel de clase como de método:
@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"
)
|
@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.
})
|
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.
|