Validar especificações da API

Esta página se aplica à Apigee e à Apigee híbrida.

Visualização — Apigee API hub linting feature

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

O hub de API oferece um Spectral linter (validador) integrado que valida a especificação da OpenAPI da API. Assim que você adiciona uma especificação OpenAPI à versão da API, o validador, que é ativado por padrão, valida a especificação e relata as descobertas no console do Google Cloud.

Observação : neste tópico, os termos linting e validating são usados de forma intercambiável. Os dois termos significam a mesma coisa.

Desativar validação da especificação

Por padrão, o linter está ativado. Para desativar o linter, no console do Google Cloud, acesse a página Hub de API > Configurações > Ações e, na seção Linting, desative a opção Linting.

Guia de estilo

Um guia de estilo é um conjunto de regras que usam o hub de API para validar uma especificação da OpenAPI. O hub de API usa um guia de estilo padrão para validar as especificações da OpenAPI. Para conferir as regras do guia de estilo padrão, consulte Regras da OpenAPI.

Observação : para adicionar suas próprias regras personalizadas, crie um novo guia de estilo que amplie o padrão. Depois de adicionar suas regras personalizadas ao novo guia de estilo, você precisará fazer o upload dele no hub da API.

Fazer upload de um novo guia de estilo

Console

Para fazer o upload de um novo guia de estilo, siga estas etapas:

1. Crie um novo estilo estendendo o guia de estilo padrão. Para mais informações, consulte Criar um conjunto de regras.
   Observação: uma etapa de validação realizada no upload gera um erro se um URL aparece na propriedade extends da regra. Por exemplo, esta é uma construção de propriedade ilegal e vai causar a falha do upload: extends: [spectral:oas", "https://mystyle.com/"].

2. No console do Google Cloud, acesse a página Hub da API > Configurações > Ações.

3. Na seção Linting, clique em Upload new style document.
4. Faça o upload do novo documento de estilo (criado na etapa 1) e clique em Salvar.

API REST

Para fazer upload de um novo guia de estilo para inspeção, envie uma solicitação PATCH para a seguinte API:

https://apihub.googleapis.com/v1/projects/PROJECT/locations/LOCATION/plugins/standard-linter/styleGuide?update_mask=contents

Para mais informações sobre a API, consulte UpdateStyleGuide.

Observação: uma etapa de validação realizada no upload gera um erro se um URL aparece na propriedade extends da regra. Por exemplo: Esta é uma construção de propriedade ilegal e vai causar falha no upload: extends: [spectral:oas", "https://mystyle.com/"].

O exemplo a seguir mostra a chamada de API para fazer upload de um guia de estilo.

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"name":"projects/test-project-1/locations/us-central1/plugins/standard-linter/styleGuide",
"contents":{  "contents": "ZXh0ZW5kczogWyJzcGVjdHJhbDpvYXMiXQo=",
  "mimeType": "text/yaml"}}' \ 
-X PATCH \
https://apihub.googleapis.com/v1/projects/test-project-1/locations/us-central1/plugins/standard-linter/styleGuide?update_mask=contents  

Fazer o download do guia de estilo padrão

Para fazer o download do guia de estilo padrão usado pelo hub da API para inspeção, siga estas etapas:

1. No console do Google Cloud, acesse a página Hub da API > Configurações > Ações.

2. Na seção Linting, clique em Fazer o download do documento de estilo padrão. Essa ação faz o download do documento de estilo padrão para o sistema local.

Faça o download do guia de estilo mais recente

Console

Para fazer o download do guia de estilo usado pelo hub da API para inspeção, siga estas etapas:

1. No console do Google Cloud, acesse a página Hub da API > Configurações > Ações.

2. Na seção Linting, clique em Download last style document. Essa ação faz o download do documento de estilo padrão para o sistema local.

API REST

Para fazer o download do guia de estilo usado pelo hub de API para inspeção, envie uma solicitação GET para a API a seguir:

https://apihub.googleapis.com/v1/projects/PROJECT/locations/LOCATION/plugins/standard-linter/styleGuide:contents

Para mais informações sobre a API, consulte GetStyleGuide.

O exemplo a seguir mostra a chamada de API para fazer o download do guia de estilo atual.

curl -X \
GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  https://apihub.googleapis.com/v1/projects/test-project-1/locations/us-central1/plugins/standard-linter/styleGuide:contents