Funciones avanzadas de OpenAPI #
OpenAPI, conocido inicialmente como Swagger, se ha convertido en el estándar de referencia para definir y documentar API RESTful. Aunque muchos desarrolladores conocen las funciones básicas de OpenAPI, como la definición de endpoints y de esquemas de respuesta, la especificación ofrece una gran cantidad de funciones avanzadas que pueden mejorar de forma considerable tus procesos de diseño y desarrollo de API. Este artículo profundiza en estas funciones avanzadas y ofrece una guía completa para aprovechar todo el potencial de OpenAPI.
Estructuras de datos complejas #
Objetos anidados #
OpenAPI admite estructuras de datos complejas, incluidos los objetos anidados, que son esenciales para modelar entidades del mundo real.
Ejemplo:
components:
schemas:
Address:
type: object
properties:
street:
type: string
city:
type: string
state:
type: string
zipCode:
type: string
User:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
email:
type: string
address:
$ref: '#/components/schemas/Address'
Arreglos de objetos #
También puedes definir arreglos de objetos para manejar colecciones de entidades.
Ejemplo:
components:
schemas:
UserList:
type: array
items:
$ref: '#/components/schemas/User'
OneOf, AnyOf y AllOf #
Estas construcciones permiten un modelado de datos más flexible y potente.
- OneOf: garantiza que una propiedad sea exactamente uno de los esquemas especificados.
- AnyOf: permite que una propiedad sea cualquiera de los esquemas especificados.
- AllOf: combina varios esquemas en un único esquema.
Ejemplo:
components:
schemas:
ErrorResponse:
type: object
properties:
code:
type: integer
message:
type: string
ValidationErrorResponse:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
- type: object
properties:
fields:
type: array
items:
type: string
Mecanismos de seguridad avanzados #
OAuth2 #
OpenAPI ofrece un soporte completo para OAuth2, un marco de autorización robusto.
Ejemplo:
components:
securitySchemes:
OAuth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: 'https://example.com/oauth/authorize'
tokenUrl: 'https://example.com/oauth/token'
scopes:
read: Grants read access
write: Grants write access
security:
- OAuth2:
- read
- write
Claves de API #
Las claves de API son una forma sencilla de controlar el acceso a tu API.
Ejemplo:
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
security:
- ApiKeyAuth: []
OpenID Connect #
OpenID Connect se basa en OAuth2 para proporcionar autenticación además de autorización.
Ejemplo:
components:
securitySchemes:
OpenID:
type: openIdConnect
openIdConnectUrl: 'https://example.com/.well-known/openid-configuration'
security:
- OpenID: []
Versionado de la API #
El versionado de tu API garantiza la compatibilidad con versiones anteriores y permite realizar mejoras de forma incremental. OpenAPI admite varias estrategias de versionado:
Versionado en la URI #
Incluye el número de versión en la URI.
Ejemplo:
servers:
- url: 'https://api.example.com/v1'
- url: 'https://api.example.com/v2'
Versionado en encabezados #
Especifica la versión en un encabezado personalizado.
Ejemplo:
components:
parameters:
apiVersion:
name: 'X-API-Version'
in: header
required: true
schema:
type: string
paths:
/users:
get:
summary: Retrieve users
parameters:
- $ref: '#/components/parameters/apiVersion'
responses:
'200':
description: A list of users
Negociación de contenido #
Usa el encabezado Accept para especificar la versión.
Ejemplo:
components:
headers:
Accept:
schema:
type: string
enum:
- application/vnd.example.v1+json
- application/vnd.example.v2+json
paths:
/users:
get:
summary: Retrieve users
responses:
'200':
description: A list of users
Extensiones #
OpenAPI admite extensiones personalizadas para añadir funcionalidades que no cubre la especificación estándar. Las extensiones llevan el prefijo x-.
Extensiones personalizadas de proveedor #
Puedes definir extensiones personalizadas para incluir metadatos o integrarte con otras herramientas.
Ejemplo:
components:
schemas:
User:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
x-internal-id: '12345'
Extensiones de OpenAPI para herramientas #
Herramientas como Swagger y Redoc admiten extensiones personalizadas para mejorar la documentación y las pruebas de la API.
Ejemplo:
x-swagger-router-controller: 'userController'
x-amples:
summary: 'Get user by ID'
value: '{ "id": 1, "name": "John Doe" }'
Links y callbacks #
Links #
Los links permiten definir relaciones entre operaciones, lo que facilita la comprensión de los flujos de trabajo de la API.
Ejemplo:
paths:
/users:
post:
summary: Create a user
responses:
'201':
description: User created
content:
application/json:
schema:
$ref: '#/components/schemas/User'
links:
GetUserById:
operationId: getUserById
parameters:
userId: '$response.body#/id'
Callbacks #
Los callbacks definen operaciones asíncronas que tu API puede invocar en otros servicios.
Ejemplo:
paths:
/webhook:
post:
summary: Register a webhook
requestBody:
content:
application/json:
schema:
type: object
properties:
callbackUrl:
type: string
responses:
'201':
description: Webhook registered
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookResponse'
callbacks:
onEvent:
'{$request.body#/callbackUrl}':
post:
summary: Event notification
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Event'
responses:
'200':
description: Event processed
Mejoras en la documentación #
Compatibilidad con Markdown #
OpenAPI permite usar descripciones con texto enriquecido en Markdown, lo que mejora la legibilidad y la usabilidad de tu documentación.
Ejemplo:
paths:
/users:
get:
summary: Retrieve a list of users
description: |
This endpoint retrieves a list of users.
**Example:**
```
GET /users
```
Documentación externa #
Enlaza a documentación externa para ofrecer explicaciones más detalladas.
Ejemplo:
components:
schemas:
User:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
externalDocs:
description: 'More info about the User schema'
url: 'https://example.com/docs/user-schema'
Herramientas para las funciones avanzadas de OpenAPI #
Swagger Codegen #
Genera bibliotecas de cliente, stubs de servidor y documentación de API a partir de definiciones OpenAPI. Swagger Codegen
OpenAPI Generator #
Es una bifurcación de Swagger Codegen que admite más lenguajes y funciones. OpenAPI Generator
Stoplight #
Una plataforma integral para el diseño, la documentación y las pruebas de API. Stoplight
Postman #
Una popular herramienta de desarrollo de API que admite la importación de OpenAPI para pruebas y documentación. Postman
Redoc #
Genera documentación de API atractiva y personalizable a partir de definiciones OpenAPI. Redoc
Conclusión #
Las funciones avanzadas de OpenAPI ofrecen un marco sólido para diseñar, documentar y gestionar API. Al aprovechar las estructuras de datos complejas, los mecanismos de seguridad avanzados, las estrategias de versionado, las extensiones personalizadas, los links y los callbacks, puedes crear API que no solo sean funcionales, sino también escalables y fáciles de usar. Herramientas como Swagger, OpenAPI Generator y Stoplight refuerzan aún más tu capacidad para implementar estas funciones de forma eficaz.
Para profundizar en la especificación OpenAPI, visita la documentación oficial de OpenAPI y consulta la documentación de Swagger y de Redoc para obtener más información sobre cómo utilizar estas funciones avanzadas en tus proyectos de API. Al dominar estas funciones avanzadas, podrás llevar el diseño y el desarrollo de tus API al siguiente nivel.
Última actualización: 28 de mayo de 2024.