¿Qué son las extensiones de OpenAPI?

¿Qué son las extensiones de OpenAPI? #

En el cambiante panorama del desarrollo de API, es fundamental garantizar que las API sean sólidas, escalables y fáciles de integrar. OpenAPI, anteriormente conocido como Swagger, se ha convertido en el estándar de facto para definir API, al ofrecer una forma independiente del lenguaje de describir las API RESTful. Aunque la especificación OpenAPI (OAS) proporciona una base completa para documentar los endpoints, los modelos de datos y las operaciones de una API, las aplicaciones del mundo real suelen tener necesidades únicas y especializadas que van más allá del estándar.

Aquí es donde entran en juego las extensiones de OpenAPI. En este artículo veremos qué son las extensiones de OpenAPI, por qué resultan útiles y cómo implementarlas de forma eficaz en la documentación de tu API.

Comprender OpenAPI #

Antes de profundizar en las extensiones, es esencial tener un conocimiento básico de la especificación OpenAPI. OpenAPI describe la estructura de tu API mediante un archivo YAML o JSON, en el que detalla los endpoints disponibles, los formatos de solicitud y respuesta, los parámetros y los métodos de autenticación.

Componentes clave de OpenAPI: #

  • Rutas (paths): Define los endpoints y los métodos HTTP permitidos.
  • Servidores (servers): Enumera los servidores en los que se aloja la API.
  • Componentes (components): Contiene elementos reutilizables como respuestas, parámetros y esquemas.
  • Seguridad (security): Describe los mecanismos de seguridad, como OAuth2 o las claves de API.

Para obtener más información sobre la estructura y los elementos de OpenAPI, puedes consultar la documentación oficial de OpenAPI.

¿Qué son las extensiones de OpenAPI? #

Las extensiones de OpenAPI, también conocidas como extensiones de proveedor (vendor extensions), permiten a los desarrolladores añadir metadatos personalizados y no estándar a sus documentos de OpenAPI. Estas extensiones ofrecen una forma de incluir información que la OAS no admite de forma nativa, lo que permite a las organizaciones adaptar la documentación de su API a requisitos específicos.

Sintaxis y convenciones #

Por convención, una extensión de OpenAPI se identifica mediante un nombre de propiedad que comienza con “x-”. Este prefijo distingue las extensiones personalizadas de los campos estándar de OpenAPI. Este es un ejemplo sencillo:

paths:
  /pets:
    get:
      summary: "List all pets"
      operationId: "listPets"
      x-rate-limit: 60

En el ejemplo anterior, x-rate-limit es una extensión personalizada que indica el límite de solicitudes para el endpoint GET /pets.

¿Por qué usar las extensiones de OpenAPI? #

Las extensiones de OpenAPI ofrecen varios beneficios para los desarrolladores de API:

  1. Personalización: Permiten incorporar datos personalizados, adaptados a tus requisitos específicos, sin alterar la especificación estándar de OpenAPI.
  2. Documentación mejorada: Con las extensiones, puedes añadir elementos descriptivos adicionales que pueden ser cruciales para los consumidores de tu API.
  3. Integraciones con herramientas: Muchas herramientas y plataformas de API admiten las extensiones de OpenAPI, lo que permite integraciones y automatizaciones más profundas. Algunos ejemplos son los API gateways, los generadores de SDK de cliente y los servicios de monitorización.

Casos de uso comunes #

Dada su flexibilidad, las extensiones de OpenAPI pueden emplearse en una gran variedad de escenarios. Estos son algunos casos de uso comunes:

Límites de solicitudes y cuotas #

Al especificar los límites de solicitudes en tu documento de OpenAPI, puedes orientar a los consumidores de la API sobre las limitaciones de uso y evitar posibles abusos.

paths:
  /pets:
    get:
      x-rate-limit: 60

Información específica de un proveedor #

Supón que utilizas servicios de terceros, como un API gateway o una herramienta de monitorización concretos. Puedes añadir información específica del proveedor mediante extensiones.

x-vendor-service:
  upstream: "api.vendor-service.com"
  region: "us-west-1"

Esquemas de seguridad personalizados #

Los mecanismos de seguridad personalizados, como los métodos de autenticación propietarios, también pueden describirse mediante extensiones.

components:
  securitySchemes:
    customAuth:
      type: "http"
      x-custom-scheme: "proprietary"

Validaciones avanzadas #

Las extensiones permiten declarar validaciones avanzadas que no están cubiertas por el esquema estándar de OpenAPI.

components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: integer
          format: int64
          x-min-value: 1

Implementar extensiones de OpenAPI #

Definir extensiones en YAML o JSON #

Añadir extensiones de OpenAPI a tu archivo YAML o JSON es sencillo. Basta con insertar las propiedades x- en los puntos correspondientes de tu documento.

Ejemplo en YAML:

openapi: 3.0.0
info:
  title: "Sample API"
  version: "1.0.0"
paths:
  /pets:
    get:
      summary: "List all pets"
      operationId: "listPets"
      x-rate-limit: 60

Ejemplo en JSON:

{
  "openapi": "3.0.0",
  "info": {
    "title": "Sample API",
    "version": "1.0.0"
  },
  "paths": {
    "/pets": {
      "get": {
        "summary": "List all pets",
        "operationId": "listPets",
        "x-rate-limit": 60
      }
    }
  }
}

Uso de herramientas compatibles con extensiones #

Muchas herramientas del ecosistema de las API reconocen y utilizan las extensiones de OpenAPI. Algunos ejemplos destacados son:

  • Swagger UI: Permite mostrar extensiones personalizadas y metadatos adicionales.
  • AWS API Gateway: Admite extensiones para diversas configuraciones específicas del gateway.
  • Postman: Puede leer las extensiones personalizadas y actuar en consecuencia para realizar pruebas y monitorización avanzadas.

Buenas prácticas #

Aunque las extensiones de OpenAPI ofrecen flexibilidad, es esencial seguir las buenas prácticas para mantener una documentación de API limpia y fácil de mantener:

  1. Coherencia: Estandariza el nombre y la estructura de tus extensiones en toda la documentación de tu API para garantizar la coherencia.
  2. Documentación: Documenta con claridad qué hace cada extensión. Esto facilita la comprensión a otros desarrolladores y a quienes mantengan la API en el futuro.
  3. Validación: Usa herramientas que admitan la validación de extensiones para asegurarte de que tus extensiones personalizadas no introduzcan errores ni conflictos.
  4. Prefijos de proveedor: Si las extensiones son específicas de un proveedor, incluye el nombre del proveedor en el prefijo de la extensión. Por ejemplo, x-vendor-feature.

Conclusión #

Las extensiones de OpenAPI son una funcionalidad potente que permite a los desarrolladores de API ampliar la documentación estándar con metadatos personalizados. Ofrecen una forma de cumplir requisitos especializados, integrarse con diversas herramientas y proporcionar información adicional que puede ser crítica para los consumidores de la API. Al comprender e implementar eficazmente las extensiones de OpenAPI, puedes crear documentación de API completa, sólida y fácil de usar, adaptada a tus necesidades particulares.

Para seguir leyendo, consulta estos recursos:

Al aprovechar el potencial de las extensiones de OpenAPI, puedes lograr que tus API no solo sean completas, sino también versátiles y capaces de adaptarse al siempre cambiante panorama de las API.

Última actualización: 29 de mayo de 2024.

Este sitio web no está afiliado a la OpenAPI Initiative.