...
Para realizar esta documentación se utilizará la librería OpenApi.
Guía detallada
Cambios a realizar:
1. pom.xml
Añadir la dependencia:
| Bloque de código |
|---|
|
<!-- 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.
| Bloque de código |
|---|
|
# SpringDoc OpenAPI Documentation
springdoc.api-docs.path=/api-docs
# Propiedades inventadas para reubicar las peticiones
springdoc.server.url=https://apidesa.um.es ### entorno correspondiente
springdoc.server.path=/mncs/api-base ### ejemplo de server.path. Debe ser /GROUP/SERVICE (ante la duda, revisar la ruta del proyecto en gitlab, por ejemplo: https://gitlab.um.es/mncs/api-base)
springdoc.security.issuer-uri=${cas.url}/cas/oidc
|
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
| Bloque de código |
|---|
|
@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
| Bloque de código |
|---|
|
@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.
})
|
Artículos Relacionados
| Contenido por etiqueta |
|---|
| showLabels | false |
|---|
| max | 5 |
|---|
| spaces | MDUYADA |
|---|
| showSpace | false |
|---|
| sort | modified |
|---|
| reverse | true |
|---|
| type | page |
|---|
| cql | label = "kb-how-to-article" and type = "page" and space = "MDUYADA" |
|---|
| labels | kb-how-to-article |
|---|
|
...