Modifica una puerta de enlace para usar OpenAPI 3.x

En esta página, se describe cómo modificar una puerta de enlace de API existente para usar una especificación de OpenAPI 3.x para su configuración de API.

Antes de comenzar

  • Confirma que tienes una instancia existente de API Gateway configurada con una especificación de OpenAPI 2.0.
  • Instala la CLI de gcloud. Para obtener más información, consulta Instala Google Cloud CLI.

Modifica la configuración de una API para usar OpenAPI 3.x

Para modificar una configuración existente de API Gateway de OpenAPI 2.0 para usar OpenAPI 3.x, completa los siguientes pasos:

Cómo encontrar la configuración actual de la API

Busca la configuración de la API asociada con tu puerta de enlace.

  1. Describe tu instancia de API Gateway:

    gcloud api-gateway gateways describe GATEWAY_ID --project=PROJECT_ID --location=GATEWAY_LOCATION

    Reemplaza lo siguiente:

    • GATEWAY_ID: Es el ID de tu puerta de enlace.
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • GATEWAY_LOCATION: Es la ubicación de tu puerta de enlace.

    El resultado muestra la ruta de acceso a apiConfig, por ejemplo:

    apiConfig: projects/my-project/locations/global/apis/my-api/configs/my-gateway-config
createTime: '2025-03-25T02:49:58.641650649Z'
defaultHostname: my-gateway-a1b2c3d4.uc.gateway.dev
displayName: My gateway
name: projects/my-project/locations/us-west1/gateways/my-new-gateway
state: ACTIVE
updateTime: '2025-03-25T02:51:52.674308428Z'

Obtén el documento de OpenAPI

Para obtener el documento de OpenAPI de la configuración de la API que identificaste, haz lo siguiente:

  1. Describe la configuración de la API:

    gcloud api-gateway api-configs describe CONFIG_ID --api=API_ID --project=PROJECT_ID --view=FULL

    Reemplaza lo siguiente:

    • CONFIG_ID: Es el ID de tu configuración de API.
    • API_ID: Es el ID de tu API.
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .

    El resultado muestra la sección openapiDocuments, que contiene el contenido codificado en Base64 de tu documento de OpenAPI:

    createTime: '2024-02-16T21:11:36.293169474Z'
displayName: my-api-config
gatewayServiceAccount: projects/-/serviceAccounts/api-gateway-sa@my-sandbox.iam.gserviceaccount.com
name: projects/my-project-id/locations/global/apis/my-api/configs/my-gateway-config
openapiDocuments:
-   document:
    contents: IyBvc...
    path: apigateway-config.yaml
serviceConfigId: my-api-config-0a1fjkfeb7t8z
state: ACTIVE
updateTime: '2024-02-16T21:13:45.626771120Z'

Decodifica el documento de OpenAPI

Para decodificar el contenido del documento de OpenAPI codificado en Base64, haz lo siguiente:

  1. Decodifica el valor de contents:

    echo 'IyBvc...' | base64 -d

    Reemplaza IyBvc... por el valor real de contents del paso anterior.

    El resultado muestra tu documento de OpenAPI 2.0, por ejemplo:

    swagger: '2.0'
info:
  title: API_ID
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0

Convierte el documento de OpenAPI a OpenAPI 3.x

Puedes usar una herramienta para convertir tu documento de OpenAPI 2.0 a OpenAPI 3.x. Por ejemplo, Swagger Editor proporciona una utilidad de conversión.

Después de la conversión inicial a OpenAPI 3.x, aplica manualmente los cambios adicionales al documento para alinearlo con OpenAPI 3.x y garantizar la compatibilidad con las extensiones y funciones de API Gateway. Para obtener más detalles sobre las extensiones de OpenAPI 3.x compatibles en API Gateway, consulta Extensiones de OpenAPI 3.x en API Gateway.

En la siguiente tabla, se describen los cambios necesarios:

Función OpenAPI 2.0 OpenAPI 3.x Descripción del cambio
Clave de API securityDefinitions securitySchemes Las claves de API usan la compatibilidad lista para usar con claves de API de OpenAPI. Por lo general, las herramientas de conversión se encargan de esto automáticamente. No se requieren cambios manuales.
Autenticación de JWT x-google-audiences, etcétera x-google-auth En las extensiones de OpenAPI 2.0, defines la configuración de OAuth con extensiones individuales en una instancia de securityDefinition. Las herramientas de conversión convierten la instancia del esquema de seguridad en #/components/securitySchemes y dejan las extensiones. Modifica manualmente estas extensiones para que sean elementos secundarios de x-google-auth y quita el prefijo x-google-. Los valores permanecen sin cambios.
Cuota x-google-management, x-google-quota x-google-api-management, x-google-quota En las extensiones de OpenAPI 2.0, defines las métricas y la cuota en x-google-management y las adjuntas con x-google-quota. Las herramientas de conversión dejan estas extensiones en su lugar. Mueve manualmente la configuración de las métricas y las cuotas de x-google-management a x-google-api-management. Cambia la configuración para usar claves YAML y quita valueType, metricKind y unit. Quita metricCosts de las instancias de x-google-quota.
Backends x-google-backend x-google-api-management, x-google-backend En las extensiones de OpenAPI 2.0, defines los backends en x-google-backend, y la configuración se aplica donde se define. En las extensiones de OpenAPI 3.x, defines el backend en x-google-api-management y, luego, lo aplicas con x-google-backend. Las herramientas de conversión dejan esta extensión en su lugar. Mueve manualmente la configuración a x-google-api-management. Modifica las instancias de x-google-backend para que hagan referencia a esa configuración.
Extremos x-google-endpoints x-google-endpoint, servers En las extensiones de OpenAPI 2.0, defines la configuración de los extremos en x-google-endpoints. En las extensiones de OpenAPI 3.x, se usa x-google-endpoint, pero es una extensión en servers en lugar de en la raíz. Las herramientas de conversión dejan esta extensión en su lugar. Mueve esto de forma manual a servers y quita el campo name. Por ejemplo: 
# OpenAPI 2.0
x-google-endpoints:
- name: "my-api.apigateway.my-project.cloud.goog"
  allowCors: True
# OpenAPI 3.0.x
servers:
- url: https://my-api.apigateway.my-project.cloud.goog/
  x-google-endpoint:
    allowCors: True
Nombres de la API x-google-api-name x-google-api-management En las extensiones de OpenAPI 2.0, defines los nombres de la API en x-google-api-name. En las extensiones de OpenAPI 3.x, se usa un campo apiName en x-google-api-management. Mueve manualmente esta configuración a x-google-api-management.
Permitir todo el tráfico x-google-allow INCOMPATIBLE Quita esto del documento de OpenAPI. API Gateway no admite esta función en OpenAPI 3.x.

Crea una nueva configuración de API

Crea una nueva configuración de API con tu documento de OpenAPI 3.x modificado.

  1. Crea la configuración de la API:

    gcloud api-gateway api-configs create NEW_CONFIG_ID --api=API_ID --project=PROJECT_ID --openapi-spec=NEW_API_DEFINITION

    Reemplaza lo siguiente:

    • NEW_CONFIG_ID: Es un ID nuevo para tu configuración de API.
    • API_ID: Es el ID de tu API.
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • NEW_API_DEFINITION: Es la ruta de acceso a tu archivo de especificación de OpenAPI 3.x.

Actualiza la puerta de enlace

Actualiza tu instancia de puerta de enlace para que haga referencia a la nueva configuración de API desde tu documento de OpenAPI 3.x modificado.

  1. Actualiza la puerta de enlace:

    gcloud api-gateway gateways update GATEWAY_ID --api-config=API_CONFIG --project=PROJECT_ID --location=GATEWAY_LOCATION

    Reemplaza lo siguiente:

    • GATEWAY_ID: Es el ID de tu puerta de enlace.
    • API_CONFIG: Es la ruta de acceso completa del recurso de la nueva configuración de la API, por ejemplo: projects/PROJECT_ID/locations/global/apis/API_ID/configs/NEW_CONFIG_ID
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • GATEWAY_LOCATION: Es la ubicación de tu puerta de enlace.

¿Qué sigue?