¿Cómo se puede usar OpenAPI con Kong API Gateway?

¿Cómo se puede usar OpenAPI con Kong API Gateway? #

Kong Gateway es uno de los API gateways de código abierto más desplegados; las organizaciones lo utilizan para gestionar, proteger y observar el tráfico de las API. Kong emplea una arquitectura de plugins que permite añadir autenticación, limitación de velocidad, registro, transformación y otras capacidades al tráfico de las API sin modificar su implementación. OpenAPI y Kong se integran de forma natural: el documento OpenAPI describe las capacidades y el contrato de la API, mientras que Kong aplica políticas al tráfico de entrada y salida de esa API. Este artículo describe las principales formas de usar OpenAPI y Kong conjuntamente.

Importar documentos OpenAPI en Kong #

El modelo de configuración de Kong se basa en Services (las implementaciones de API upstream) y Routes (patrones de URL que asocian las solicitudes entrantes con un servicio). Históricamente, configurar Kong requería definir Services, Routes y Plugins manualmente mediante la Admin API de Kong, una configuración declarativa en YAML o una interfaz gráfica.

Ahora Kong permite importar documentos OpenAPI para generar esta configuración automáticamente. Los dos métodos principales son Insomnia (la herramienta de diseño de API de Kong) y deck (la CLI de configuración declarativa de Kong).

Método 1: deck con openapi2kong #

deck es la herramienta oficial de Kong para la gestión de configuración declarativa. Incluye el comando deck file openapi2kong, que convierte un documento OpenAPI en un archivo de configuración declarativa de Kong:

deck file openapi2kong \
  --spec openapi.yaml \
  --output-file kong.yaml

Esto genera un archivo kong.yaml que contiene:

  • Un service correspondiente al servidor upstream de la API (servers[0].url)
  • Una route por cada operación del documento OpenAPI, con el patrón de ruta y el método HTTP correctos
  • Opcionalmente, plugins derivados de los esquemas de seguridad de OpenAPI

A continuación, la configuración generada se puede sincronizar con una instancia de Kong en ejecución:

deck gateway sync kong.yaml

Este flujo de trabajo convierte el documento OpenAPI en la fuente de verdad de la configuración de enrutamiento de Kong. Cuando se añaden nuevos endpoints al documento OpenAPI, regenerar y sincronizar la configuración de deck actualiza automáticamente la tabla de enrutamiento de Kong.

Método 2: Kong Insomnia #

Insomnia es la herramienta de diseño y pruebas de API de Kong. Insomnia puede importar documentos OpenAPI y generar un espacio de trabajo de pruebas (similar a Postman), pero además dispone de un flujo de diseño que publica documentos OpenAPI directamente en Kong Konnect (la plataforma en la nube gestionada de Kong). Los equipos usan Insomnia para diseñar la API en OpenAPI, probarla y desplegar la configuración del gateway desde una sola herramienta.

Generar rutas a partir de las rutas de OpenAPI #

La conversión de openapi2kong asigna los elementos de ruta de OpenAPI a rutas (routes) de Kong. Los parámetros de ruta se convierten a la sintaxis de variables de ruta de Kong:

Ruta de OpenAPIRuta de Kong
/users/{userId}/users/$(uri_captures.userId) o /users/{userId}
/orders/{orderId}/items/orders/{orderId}/items
/health/health

Cada route se configura con los métodos HTTP de la operación de OpenAPI (por ejemplo, una route para GET /users solo coincidirá con solicitudes GET).

Autenticación a partir de los esquemas de seguridad de OpenAPI #

Los esquemas de seguridad de OpenAPI se pueden usar para configurar los plugins de autenticación de Kong. La herramienta openapi2kong traduce los esquemas de seguridad más comunes:

  • http bearer → plugin jwt de Kong
  • apiKey en el encabezado → plugin key-auth de Kong
  • oauth2 → plugin oauth2 de Kong

Por ejemplo, un documento OpenAPI con:

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - BearerAuth: []

Puede generar una configuración de Kong que aplique el plugin jwt a todas las routes derivadas del documento.

Limitación de velocidad a partir de extensiones de OpenAPI #

Kong admite campos de extensión de OpenAPI (con el prefijo x-) para incluir configuración específica de Kong que no se puede expresar en OpenAPI estándar. Esto permite a quienes diseñan la API especificar la limitación de velocidad, la configuración de plugins y otros ajustes del gateway directamente en el documento OpenAPI:

paths:
  /search:
    get:
      summary: Search products
      x-kong-plugin-rate-limiting:
        enabled: true
        config:
          minute: 100
          hour: 1000
          policy: local
      responses:
        "200":
          ...

El comando deck file openapi2kong procesa estas extensiones e incluye la configuración de plugins correspondiente en la configuración declarativa de Kong generada.

Plugin de validación de solicitudes #

El plugin Request Validator de Kong puede validar las solicitudes entrantes frente a los esquemas de parámetros y de cuerpo de la solicitud definidos en un documento OpenAPI. Así, la validación se traslada a la capa del gateway, antes de que la solicitud llegue a la API upstream:

# Kong declarative config with request validation
services:
  - name: my-api
    url: http://api.internal
    routes:
      - name: create-user
        methods: [POST]
        paths: [/users]
        plugins:
          - name: request-validator
            config:
              body_schema: |
                {
                  "type": "object",
                  "required": ["email", "name"],
                  "properties": {
                    "email": {"type": "string", "format": "email"},
                    "name": {"type": "string"}
                  }
                }
              verbose_response: true

Cuando la configuración de deck se genera a partir de OpenAPI, los esquemas de solicitud de requestBody pueden incluirse en la configuración del plugin de validación de solicitudes, lo que permite aplicar automáticamente la validación de entradas en el gateway.

Plugin de validación de OAS (Kong Enterprise) #

Kong Enterprise (la versión comercial) incluye el plugin OAS Validation, que toma el documento OpenAPI completo como configuración y valida tanto la solicitud como la respuesta frente a la especificación en tiempo real. Esto proporciona una aplicación automática del contrato en el gateway sin necesidad de extraer y duplicar los esquemas en configuraciones de plugins independientes.

Integración con CI/CD #

El flujo OpenAPI → Kong se integra de forma natural en los pipelines de CI/CD:

# GitHub Actions example
jobs:
  deploy-gateway:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate OpenAPI document
        run: npx @stoplight/spectral-cli lint openapi.yaml --ruleset .spectral.yaml

      - name: Convert OpenAPI to Kong config
        run: deck file openapi2kong --spec openapi.yaml --output-file kong.yaml

      - name: Diff against current gateway config
        run: deck gateway diff kong.yaml

      - name: Sync to Kong
        run: deck gateway sync kong.yaml
        env:
          KONG_ADDR: ${{ secrets.KONG_ADMIN_URL }}
          KONG_TOKEN: ${{ secrets.KONG_ADMIN_TOKEN }}

Este pipeline valida el documento OpenAPI con Spectral, lo convierte en una configuración de Kong, muestra un diff de lo que cambiará y, a continuación, sincroniza los cambios con el gateway en ejecución. El documento OpenAPI se convierte en la única fuente de verdad tanto del contrato de la API como de la configuración del gateway.

Konnect API Hub #

Kong Konnect (la plataforma en la nube de Kong) incluye un API Hub, un portal para desarrolladores donde los consumidores de API pueden explorar las API disponibles y su documentación. Los documentos OpenAPI que se suben a Konnect se muestran como documentación de API interactiva (con el motor de renderizado de Insomnia), lo que proporciona un portal para desarrolladores integrado sin necesidad de herramientas adicionales.

Conclusión #

Kong y OpenAPI se complementan en todas las etapas del ciclo de vida de la API. El documento OpenAPI define el contrato de la API; Kong aplica políticas al tráfico de entrada y salida de esa API. Con herramientas como deck y openapi2kong, el documento OpenAPI puede dirigir automáticamente la configuración de enrutamiento de Kong, la configuración de autenticación y la del plugin de validación de solicitudes. Integrado en un pipeline de CI/CD, este enfoque elimina el desfase entre la documentación de la API y la configuración del gateway, garantizando que lo documentado y lo aplicado estén siempre sincronizados.

Última actualización: 30 de abril de 2026.

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