Historial de página

...

<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>

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.

...

            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.

...

 @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 endpoints servicios controlen y devuelvan un conjunto de respuestas completos, según la situación controladalas 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

...