MicroProfile Open API
Para una API, es necesario definir un contrato, este contendrá las reglas y los detalles para consumir la API. En la API restful, OpenAPI (swagger) se ha convertido en el contrato más utilizado para tal fin. Desde el primer momento, MicroProfile brinda soporte para Open API y genera un archivo YAML con los detalles de nuestros servicios Restful; y podemos verlo en el endpoint /openapi.
Open API nos permite agregar más detalles a nuestros recursos Restful como descripciones, códigos de estado, ejemplos de retorno, detalles de parámetros y más al agregar algunas anotaciones en nuestro código. Veamos un ejemplo usando el método findById en la clase BookResource en la aplicación item-service.
@GET
@Path("/{id}")
@Produces(MediaType.APPLICATION_JSON)
@APIResponses(
value = {
@APIResponse(
responseCode = "404",
description = "Book not found"),
@APIResponse(
responseCode = "200",
description = "Book is found and returned",
content = @Content(schema = @Schema(implementation = Book.class)))
})
@Operation(
summary = "Finds a book by its Id",
description = "Finds a book by its Id … more details…")
public Book findById(
@Parameter(description = "Book's Id", required = true) @PathParam("id") Long id) {
return service.findById(id).orElseThrow(NotFoundException::new);
}Luego, recomiendo agregar la siguiente dependencia para proporcionar una página Swagger-UI que muestre los detalles en nuestro archivo openapi.yaml.
<dependency>
<groupId>org.microprofile-ext.openapi-ext</groupId>
<artifactId>swagger-ui</artifactId>
<version>1.0.3</version>
<scope>runtime</scope>
</dependency> Es hora de ver la documentación de nuestros Recursos, por lo que solo nos falta acceder al endpoint /<appcontext>/api/openapi-ui. En nuestro caso, http://localhost:8080/items-service/api/openapi-ui
