Esta página se ha traducido con Cloud Translation API.

Modificar una pasarela para usar OpenAPI 3.x

En esta página se describe cómo modificar una pasarela de API para que use una especificación de OpenAPI 3.x en su configuración de API.

Antes de empezar

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

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

Para modificar una configuración de API Gateway de OpenAPI 2.0 y usar OpenAPI 3.x, sigue estos pasos:

Buscar la configuración actual de la API

Busca la configuración de API asociada a tu pasarela.

Describe tu instancia de API Gateway:

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

Haz los cambios siguientes:

GATEWAY_ID: el ID de tu pasarela.
PROJECT_ID: tu ID de proyecto Google Cloud .
GATEWAY_LOCATION: la ubicación de tu pasarela.

En la salida se muestra la ruta de 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'

Obtener el documento OpenAPI

Para obtener el documento de OpenAPI de la configuración de la API que has identificado, sigue estos pasos:

Describe la configuración de la API:

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

Haz los cambios siguientes:

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

En la salida se 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'

Decodificar el documento OpenAPI

Para decodificar el contenido del documento OpenAPI codificado en Base64, sigue estos pasos:

Decodifica el valor de contents:

echo 'IyBvc...' | base64 -d

Sustituye IyBvc... por el valor contents del paso anterior.

El resultado muestra tu documento 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

Convertir el documento OpenAPI a OpenAPI 3.x

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

Después de la conversión inicial a OpenAPI 3.x, aplica manualmente los cambios adicionales al documento para que se ajuste a OpenAPI 3.x y asegúrate de que sea compatible con las extensiones y funciones de API Gateway. Para obtener más información sobre las extensiones de OpenAPI 3.x admitidas en API Gateway, consulta el artículo 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 con claves de API de OpenAPI lista para usar. Las herramientas de conversión suelen encargarse de esto automáticamente. No es necesario hacer ningún cambio manualmente.
Autenticación JWT	`x-google-audiences`, etc.	`x-google-auth`	En las extensiones de OpenAPI 2.0, la configuración de OAuth se define 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 no cambian.
Cuota	`x-google-management`, `x-google-quota`	`x-google-api-management`, `x-google-quota`	En las extensiones de OpenAPI 2.0, se definen las métricas y las cuotas en `x-google-management` y se adjuntan con `x-google-quota`. Las herramientas de conversión dejan estas extensiones en su sitio. Mueve manualmente las métricas y la configuración de cuota de `x-google-management` a `x-google-api-management`. Cambia la configuración para usar claves YAML y elimina `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, los backends se definen en `x-google-backend` y la configuración se aplica donde se define. En las extensiones de OpenAPI 3.x, se define el backend en `x-google-api-management` y, a continuación, se aplica con `x-google-backend`. Las herramientas de conversión dejan esta extensión en su sitio. 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.
Endpoints	`x-google-endpoints`	`x-google-endpoint`, `servers`	En las extensiones de OpenAPI 2.0, se define la configuración de los endpoints en `x-google-endpoints`. En las extensiones de OpenAPI 3.x, se usa `x-google-endpoint`, pero es una extensión de `servers` en lugar de la raíz. Las herramientas de conversión dejan esta extensión en su sitio. Mueve manualmente este elemento a `servers` y elimina 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 las APIs	`x-google-api-name`	`x-google-api-management`	En las extensiones de OpenAPI 2.0, los nombres de las APIs se definen 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`	NO COMPATIBLE	Elimina esto del documento de OpenAPI. API Gateway no admite esta función en OpenAPI 3.x.

Crear una configuración de API

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

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
```
Haz los cambios siguientes:
- NEW_CONFIG_ID: un nuevo ID para la configuración de tu API.
- API_ID: el ID de tu API.
- PROJECT_ID: tu ID de proyecto Google Cloud .
- NEW_API_DEFINITION: la ruta al archivo de especificación OpenAPI 3.x.

Actualizar la pasarela

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

Actualiza la pasarela:
```
gcloud api-gateway gateways update GATEWAY_ID --api-config=API_CONFIG --project=PROJECT_ID --location=GATEWAY_LOCATION
```
Haz los cambios siguientes:
- GATEWAY_ID: el ID de tu pasarela.
- API_CONFIG: la ruta 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: tu ID de proyecto Google Cloud .
- GATEWAY_LOCATION: la ubicación de tu pasarela.

Siguientes pasos

Consulta más información sobre API Gateway.
Consulta la especificación de OpenAPI.