Nesta página, descrevemos como usar uma especificação do OpenAPI 3.x ao configurar o Endpoints.
Antes de começar
- Confirme se você tem uma instância do Endpoints configurada com uma especificação OpenAPI 2.0.
- Instale a CLI
gcloud. Para mais informações, consulte Instalar a Google Cloud CLI.
Modificar a configuração do Endpoints para usar o OpenAPI 3.x
Siga estas etapas para modificar uma configuração do Endpoints OpenAPI 2.0 e usar o OpenAPI 3.x.
Conferir o histórico de implantação
Basta seguir estas etapas:
No Google Cloud console, acesse a página Endpoints > Serviços.
Selecione um projeto na lista.
Se você tiver mais de uma API, selecione a que você quer na lista.
Para ver uma lista de implantações de configuração de serviço, clique na guia Histórico de implantação. A lista exibe:
- o código de configuração;
- a data em que a configuração de serviço foi implantada;
- quem implantou a configuração.
Ver a configuração do serviço
Na guia Histórico de implantações, selecione a implantação mais recente na lista. O conteúdo do arquivo de configuração de serviço implantado é exibido.
Converter o documento da OpenAPI para a OpenAPI 3.x
Converta seu documento OpenAPI 2.0 para OpenAPI 3.x. É possível usar uma ferramenta que ofereça suporte a essa conversão para 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 extensões e recursos do Endpoints.
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.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 Endpoints não oferece suporte a isso na OpenAPI 3.x. |
Reimplantar a configuração do serviço
Sempre que você fizer mudanças no documento da OpenAPI, implante-o novamente para que a versão mais recente da configuração da API esteja disponível para o Endpoints. Não é necessário reimplantar ou reiniciar o ESP se você já tiver implementado o ESP com a opção rollout definida como managed.
O ESP é configurado para usar a implantação mais recente da configuração do serviço. Quando você especifica essa opção, até 5 minutos depois de implantar uma nova configuração de serviço, o ESP detecta a alteração e começa a usá-la automaticamente. Recomendamos especificar essa opção em vez de um ID de configuração específico para uso do ESP.
Para implantar o documento da OpenAPI:
Altere o diretório para o local que contém o documento do OpenAPI.
Valide o código do projeto retornado do seguinte comando para garantir que o serviço não seja criado no projeto incorreto.
gcloud config list projectSe você precisar mudar o projeto padrão, execute o seguinte comando e substitua YOUR_PROJECT_ID pelo ID do projeto Google Cloud em que você quer criar o serviço:
gcloud config set project <var>YOUR_PROJECT_ID</var>Execute o seguinte comando e substitua YOUR_OPENAPI_DOCUMENT pelo nome do documento do OpenAPI que descreve a API:
gcloud endpoints services deploy <var>YOUR_OPENAPI_DOCUMENT</var>
Na primeira vez que você executa o comando anterior, o Service Management cria um novo serviço do Endpoints no projeto padrão com um nome que corresponde ao texto especificado no campo host no documento da OpenAPI e envia a configuração do serviço.
Durante a criação e a configuração do serviço, o Service Management envia informações ao terminal. Após a conclusão, uma linha semelhante a esta é exibida com o ID da configuração e o nome do serviço:
Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]
No exemplo anterior, 2017-02-13r0 é o ID de configuração do serviço e echo-api.endpoints.example-project-12345.cloud.goog é o nome do serviço.
Depois de realizar a implantação, é possível ver a API na página Endpoints > Serviços no Google Cloud console.
Se você receber uma mensagem de erro, consulte Como solucionar problemas de implantação na configuração do Endpoints.