Esta página foi traduzida pela API Cloud Translation.

Modificar um gateway para usar o OpenAPI 3.x

Nesta página, descrevemos como modificar um gateway de API para usar uma especificação OpenAPI 3.x na configuração da API.

Antes de começar

Confirme se você tem uma instância do gateway de API configurada com uma especificação OpenAPI 2.0.
Instale a CLI gcloud. Para mais informações, consulte Instalar a Google Cloud CLI.

Modificar uma configuração de API para usar o OpenAPI 3.x

Para modificar uma configuração do gateway de API OpenAPI 2.0 e usar o OpenAPI 3.x, siga estas etapas:

Encontrar a configuração atual da API

Encontre a configuração de API associada ao gateway.

Descreva sua instância do gateway de API:

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

Substitua:

GATEWAY_ID: o ID do gateway.
PROJECT_ID: o ID do projeto do Google Cloud .
GATEWAY_LOCATION: o local do gateway.

A saída mostra o caminho apiConfig. Por exemplo:

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'

Extrair o documento OpenAPI

Para acessar o documento OpenAPI da configuração de API identificada:

Descreva a configuração da API:

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

Substitua:

CONFIG_ID: o ID da sua configuração de API.
API_ID: o ID da sua API.
PROJECT_ID: o ID do projeto do Google Cloud .

A saída mostra a seção openapiDocuments, que contém o conteúdo codificado em base64 do seu documento 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 o documento OpenAPI

Para decodificar o conteúdo do documento OpenAPI codificado em base64:

Decodifique o valor contents:

echo 'IyBvc...' | base64 -d

Substitua IyBvc... pelo valor contents real da etapa anterior.

A saída mostra o documento OpenAPI 2.0. Por exemplo:

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

Converter o documento OpenAPI para OpenAPI 3.x

É possível usar uma ferramenta para converter seu documento OpenAPI 2.0 em OpenAPI 3.x. Por exemplo, o Swagger Editor oferece um utilitário de conversão.

Depois da conversão inicial para OpenAPI 3.x, aplique manualmente outras mudanças ao documento para alinhar com o OpenAPI 3.x e garantir a compatibilidade com as extensões e recursos do API Gateway. Para mais detalhes sobre a extensão OpenAPI 3.x compatível no gateway de API, consulte Extensões OpenAPI 3.x no gateway de API.

A tabela a seguir descreve as mudanças necessárias:

Recurso	OpenAPI 2.0	OpenAPI 3.x	Descrição da mudança
Chave de API	`securityDefinitions`	`securitySchemes`	As chaves de API usam o suporte pronto para uso do OpenAPI. As ferramentas de conversão geralmente fazem isso de forma automática. Não são necessárias mudanças manuais.
Autenticação JWT	`x-google-audiences` etc.	`x-google-auth`	Nas extensões do OpenAPI 2.0, você define a configuração do OAuth com extensões individuais em uma instância `securityDefinition`. As ferramentas de conversão convertem a instância do esquema de segurança em `#/components/securitySchemes` e deixam as extensões. Modifique manualmente essas extensões para serem filhos de `x-google-auth` e remova o prefixo `x-google-`. Os valores permanecem os mesmos.
Cota	`x-google-management`, `x-google-quota`	`x-google-api-management`, `x-google-quota`	Nas extensões do OpenAPI 2.0, você define métricas e cota em `x-google-management` e as anexa com `x-google-quota`. As ferramentas de conversão deixam essas extensões no lugar. Mova manualmente as métricas e a configuração de cota de `x-google-management` para `x-google-api-management`. Mude a configuração para usar chaves YAML e remova `valueType`, `metricKind` e `unit`. Remova `metricCosts` das instâncias de `x-google-quota`.
Back-ends	`x-google-backend`	`x-google-api-management`, `x-google-backend`	Nas extensões da OpenAPI 2.0, você define back-ends em `x-google-backend`, e a configuração é aplicada onde definida. Nas extensões OpenAPI 3.x, você define o back-end em `x-google-api-management` e o aplica com `x-google-backend`. As ferramentas de conversão deixam essa extensão no lugar. Mova manualmente a configuração para `x-google-api-management`. Modifique as instâncias de `x-google-backend` para referenciar essa configuração.
Endpoints	`x-google-endpoints`	`x-google-endpoint`, `servers`	Nas extensões do OpenAPI 2.0, você define a configuração de endpoints em `x-google-endpoints`. Nas extensões da OpenAPI 3.x, você usa `x-google-endpoint`, mas é uma extensão em `servers` em vez de na raiz. As ferramentas de conversão deixam essa extensão no lugar. Mova manualmente para `servers` e remova o campo `name`. Exemplo: # 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
Nomes de APIs	`x-google-api-name`	`x-google-api-management`	Nas extensões do OpenAPI 2.0, você define os nomes das APIs em `x-google-api-name`. Nas extensões da OpenAPI 3.x, você usa um campo `apiName` em `x-google-api-management`. Mova manualmente essa configuração para `x-google-api-management`.
Permitir todo o tráfego	`x-google-allow`	INCOMPATÍVEL	Remova isso do documento da OpenAPI. O gateway de API não oferece suporte a isso na OpenAPI 3.x.

Criar uma configuração de API

Crie uma configuração de API usando o documento OpenAPI 3.x modificado.

Crie a configuração da API:
```
gcloud api-gateway api-configs create NEW_CONFIG_ID --api=API_ID --project=PROJECT_ID --openapi-spec=NEW_API_DEFINITION
```
Substitua:
- NEW_CONFIG_ID: um novo ID para sua configuração de API.
- API_ID: o ID da sua API.
- PROJECT_ID: o ID do projeto do Google Cloud .
- NEW_API_DEFINITION: o caminho para o arquivo de especificação OpenAPI 3.x.

Atualizar o gateway

Atualize a instância do gateway para referenciar a nova configuração de API no documento OpenAPI 3.x modificado.

Atualize o gateway:
```
gcloud api-gateway gateways update GATEWAY_ID --api-config=API_CONFIG --project=PROJECT_ID --location=GATEWAY_LOCATION
```
Substitua:
- GATEWAY_ID: o ID do gateway.
- API_CONFIG: o caminho completo do recurso da sua nova configuração de API. Por exemplo: projects/PROJECT_ID/locations/global/apis/API_ID/configs/NEW_CONFIG_ID
- PROJECT_ID: o ID do projeto do Google Cloud .
- GATEWAY_LOCATION: o local do gateway.

A seguir

Saiba mais sobre o API Gateway.
Confira a especificação OpenAPI.