Especificación OpenAPI 3.0
- Onesait Platform
¿Qué es?
OpenAPI es un descriptor de APIs con el cual se pueden diseñar, construir, documentar y consumir APIs REST. Un fichero de OpenAPI nos permite describir nuestra API entera incluyendo:
Todos los endpoints disponibles con la operación que le corresponda (GET, POST, DELETE...)
Parametros de entrada y de salida para cada una de las operaciones.
Métodos de autenticación y seguridad.
Información de contacto, licencias, condiciones de uso y más información.
Para realizar todas estas tareas se usará Swagger, un conjunto de herramientas que se basan en todas las especificaciones de OpenAPI, para poder diseñar y construir nuestras APIs para que puedan ser consultadas y consumidas por los diferentes usuarios.
El principal propósito es tener una Interfaz Autodocumentada, dónde se determina como mínimo la siguiente información
Info:
Title: Título de la API
Description: Descripción de la API.
Versión: Versión de la interfaz.
Servers:
URL: Del entorno real y el Sandbox.
Description: Descripción del entorno.
Paths:
Summary: Descripción para qué sirve la operación (Para cada operación/path)
Description: Descripción ampliada.
Schema: Estructura de datos entrada.
Required: Indicador de si es requerido o no el dato.
Schema: Estructura de datos devueltos.
Examples: Ejemplos de datos de entrada.
Security: Tipo de seguridad permitidas.
Swagger
Las herramientas de Swagger se encuentran disponibles para ser usadas como librería para añadir como dependencia a nuestro proyecto. A partir de ella tendremos acceso a poder usar las diferentes posibilidades que nos ofrece Swagger:
Etiquetas: Mediante el uso de etiquetas de Spring podremos definir nuestras operaciones y controladores para que sean mostrados en la documentación generada por Swagger.
Configuración: Se puede definir una clase de configuración en la que añadir toda la configuración extra que se desee (como sería el caso de la autenticación).
Cambios de Swagger 2 a Swagger 3
En el caso de hacer uso de actualmente de Swagger 2 y se desee hacer el cambio a Swagger 3 dejamos un listado de cambios importantes en las etiquetas usadas desde Spring con el cambio de versión:
Swagger2 → Swagger3
@Api →@Tag
@ApiIgnore → @Parameter(hidden = true) o @Operation(hidden = true) o @Hidden
@ApiImplicitParam → @Parameter
@ApiImplicitParams → @Parameters
@ApiModel → @Schema
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
@ApiModelProperty → @Schema
@ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
@ApiParam → @Parameter
@ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")
Documentación Oficial
Para más información consultar la documentación oficial o la guía de uso.
Guía de uso Onesait
Puedes encontrar nuestra receta Onesait de como utilizarlo en Guía de uso de OpenAPI 3