Esta página foi traduzida pela API Cloud Translation.

Modifique um gateway para usar a OpenAPI 3.x

Esta página descreve como modificar um gateway de API existente para usar uma especificação OpenAPI 3.x para a respetiva configuração de API.

Antes de começar

Confirme que tem uma instância do API Gateway configurada com uma especificação OpenAPI 2.0.
Instale a CLI gcloud. Para mais informações, consulte o artigo Instale a CLI Google Cloud.

Modifique uma configuração da API para usar a OpenAPI 3.x

Para modificar uma configuração existente da API Gateway OpenAPI 2.0 para usar a OpenAPI 3.x, conclua os seguintes passos:

Encontre a configuração atual da API

Encontre a configuração da API associada ao seu gateway.

Descreva a sua instância do API Gateway:

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

Substitua o seguinte:

GATEWAY_ID: o ID da sua gateway.
PROJECT_ID: o ID do seu Google Cloud projeto.
GATEWAY_LOCATION: a localização da sua gateway.

O resultado apresenta 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'

Obtenha o documento OpenAPI

Para obter o documento OpenAPI da configuração da API que identificou:

Descreva a configuração da API:

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

Substitua o seguinte:

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

A saída apresenta a secçã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'

Descodifique o documento OpenAPI

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

Descodifique o valor de contents:

echo 'IyBvc...' | base64 -d

Substitua IyBvc... pelo valor contents real do passo anterior.

O resultado apresenta o seu 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

Converta o documento OpenAPI para OpenAPI 3.x

Pode usar uma ferramenta para converter o seu documento OpenAPI 2.0 em OpenAPI 3.x. Por exemplo, o Swagger Editor oferece uma utilidade de conversão.

Após a conversão inicial para o formato OpenAPI 3.x, aplique manualmente quaisquer alterações adicionais ao documento para se alinhar com o formato OpenAPI 3.x e garantir a compatibilidade com as extensões e as funcionalidades do API Gateway. Para mais detalhes sobre a extensão OpenAPI 3.x suportada no gateway da API, consulte o artigo Extensões OpenAPI 3.x no gateway da API.

A tabela seguinte descreve as alterações necessárias:

Funcionalidade	OpenAPI 2.0	OpenAPI 3.x	Descrição da alteração
Chave da API	`securityDefinitions`	`securitySchemes`	As chaves da API usam o suporte de chaves da API OpenAPI pronto a usar. Normalmente, as ferramentas de conversão processam esta situação automaticamente. Não são necessárias alterações manuais.
Autenticação JWT	`x-google-audiences`, etc.	`x-google-auth`	Nas extensões OpenAPI 2.0, define a configuração OAuth com extensões individuais numa 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 estas extensões para que sejam filhas de `x-google-auth` e remova o prefixo `x-google-`. Os valores permanecem inalterados.
Quota	`x-google-management`, `x-google-quota`	`x-google-api-management`, `x-google-quota`	Nas extensões OpenAPI 2.0, define métricas e quotas em `x-google-management` e anexa-as com `x-google-quota`. As ferramentas de conversão mantêm estas extensões. Mova manualmente as métricas e a configuração de quota de `x-google-management` para `x-google-api-management`. Altere 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 OpenAPI 2.0, define back-ends em `x-google-backend` e a configuração aplica-se onde está definida. Nas extensões OpenAPI 3.x, define o back-end em `x-google-api-management` e, em seguida, aplica-o com `x-google-backend`. As ferramentas de conversão mantêm esta extensão no lugar. Mova manualmente a configuração para `x-google-api-management`. Modifique as instâncias de `x-google-backend` para fazer referência a essa configuração.
Pontos finais	`x-google-endpoints`	`x-google-endpoint`, `servers`	Nas extensões OpenAPI 2.0, define a configuração dos pontos finais em `x-google-endpoints`. Nas extensões OpenAPI 3.x, usa `x-google-endpoint`, mas é uma extensão em `servers` e não na raiz. As ferramentas de conversão mantêm esta extensão no lugar. Mova-o manualmente para `servers` e remova o campo `name`. Por 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 das APIs	`x-google-api-name`	`x-google-api-management`	Nas extensões OpenAPI 2.0, define os nomes das APIs em `x-google-api-name`. Nas extensões OpenAPI 3.x, usa um campo `apiName` em `x-google-api-management`. Mova manualmente esta configuração para `x-google-api-management`.
Permitir todo o tráfego	`x-google-allow`	NÃO SUPORTADO	Remova-o do documento OpenAPI. O gateway da API não suporta esta funcionalidade no formato OpenAPI 3.x.

Crie uma nova configuração da API

Crie uma nova configuração da API com o seu 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 o seguinte:
- NEW_CONFIG_ID: um novo ID para a configuração da API.
- API_ID: o ID da sua API.
- PROJECT_ID: o ID do seu Google Cloud projeto.
- NEW_API_DEFINITION: o caminho para o ficheiro de especificação OpenAPI 3.x.

Atualize o gateway

Atualize a instância do gateway para referenciar a nova configuração da API a partir do 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 o seguinte:
- GATEWAY_ID: o ID da sua gateway.
- API_CONFIG: O caminho completo do recurso da nova configuração da API, por exemplo: projects/PROJECT_ID/locations/global/apis/API_ID/configs/NEW_CONFIG_ID
- PROJECT_ID: o ID do seu Google Cloud projeto.
- GATEWAY_LOCATION: a localização da sua gateway.

O que se segue?

Saiba mais acerca do API Gateway.
Explore a especificação OpenAPI.