Gerenciar especificações da API

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

Neste documento, descrevemos como gerenciar as especificações da API no Hub de API. Consulte também Introdução às especificações da API.

Adicionar uma especificação de API a uma versão

É possível adicionar uma ou mais especificações a uma versão da API. Escolha uma destas opções:

Adicionar uma especificação ao criar uma versão
Adicionar uma especificação a uma versão atual

Adicionar uma especificação ao criar uma versão

Usando apenas a interface, é possível adicionar uma especificação de API ao criar uma versão. Forneça o URL para uma especificação que pode ser acessada ou faça upload de um arquivo de especificação diretamente do seu sistema.

Console

Para adicionar uma especificação a uma nova versão:

Siga as etapas listadas em Criar uma versão da API para começar. Na página Adicionar uma nova versão, você tem a opção de adicionar um arquivo de especificação à versão:
1. Insira um nome de exibição para o arquivo de especificação. Use o nome que preferir.
2. Selecione o tipo de arquivo de especificação. O tipo de especificação é um sistema configurável . Consulte também Atributos do sistema.
3. Forneça um URI que aponte para um arquivo de especificação de API válido ao qual você tenha acesso ou navegue até um arquivo de especificação de API no seu sistema.
4. (Opcional) Se você quiser aplicar uma validação rígida à especificação enviada, selecione a caixa de seleção Restringir o upload do arquivo de especificações que contém erros. Quando essa opção é selecionada, uma especificação que contém erros de validação não será enviada. Por padrão, as especificações com erros são enviadas por upload.
Preencha a página Adicionar uma nova versão e clique em Criar quando terminar.

Adicionar uma especificação a uma versão atual

É possível usar a interface ou a API REST para adicionar uma especificação de API a uma versão atual.

Console

Para adicionar uma especificação diretamente a uma versão:

No console do Google Cloud, acesse a página Hub de APIs.
Acesse o hub de API
Clique em APIs.
Localize a API com a versão que você quer modificar. Use Filtro para especificar palavras-chave e filtrar a lista de APIs. Se necessário, use a Pesquisa para localizar uma API.
Selecionar uma API.
Clique em Adicionar arquivo de especificação.
Insira um nome de exibição para o arquivo de especificação. Use o nome que preferir.
Selecione o tipo de arquivo de especificação. O tipo de especificação é um atributo de sistema configurável. Consulte também Atributos do sistema.
Forneça um URI que aponte para um arquivo de especificação de API válido ao qual você tenha acesso ou navegue até um arquivo de especificação de API no seu sistema.
(Opcional) Se você quiser aplicar uma validação rígida à especificação enviada, selecione a caixa de seleção Restringir o upload do arquivo de especificações que contém erros. Quando essa opção é selecionada, uma especificação que contém erros de validação não será enviada. Por padrão, as especificações com erros são enviadas por upload.
Selecione a versão para adicionar o arquivo de especificação.
Clique em Criar.
Observação: a análise da especificação da API é compatível apenas com as especificações da OpenAPI (v.2.0, v3.0 e v3.1) nos formatos JSON e YAML.

REST

Para adicionar uma especificação de API a uma versão, use a API Add API spec:

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  'https://apihub.googleapis.com/v1/projects/API_PROJECT/locations/API_LOCATION/apis/API_ID/versions/VERSION_ID/specs?spec_id=SPEC_ID' \
  -d "DATA_FILE or URI"

Substitua:

API_PROJECT: o nome do projeto host do hub da API. O projeto host foi selecionado quando o hub de API foi provisionado.
API_LOCATION: o local do projeto host. O local foi escolhido quando o hub da API foi provisionado.
API_ID: o ID exclusivo de um recurso da API.
VERSION_ID: o ID de uma versão anexada ao recurso da API.
SPEC_ID: (opcional) o identificador da especificação. Caso não seja informado, um ID gerado pelo sistema será usado. O nome precisa ser uma string de 4 a 63 caracteres, em que os caracteres válidos são /[a-z][0-9]-/.
DATA_FILE or URI: um arquivo codificado em Base64 contendo uma especificação de API válida ou um link para uma especificação. Consulte o exemplo REST.

Exemplo de REST

Neste exemplo, crie uma nova especificação no hub da API com uma especificação OpenAPI codificada em Base64. Após o upload, o hub da API analisa a especificação e cria uma nova entidade que inclui metadados descritivos e conjuntos de entidades de operação e definição.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d "@data.json" \
  https://apihub.googleapis.com/v1/projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs?spec_id=dstreetcarts-spec

Exemplo de resposta:

{
    "name": "projects/common-dev-1/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec",
    "displayName": "Test Spec 1",
    "specType": {},
    "contents": {
      "contents": [Base64-encoded contents of an OpenAPI 3.0.2 file] },
    "details": {
      "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.\nYou can find out more about Swagger at [https://swagger.io](https://swagger.io).",
      "openApiSpecDetails": {
        "format": "OPEN_API_SPEC_3_0",
        "version": "1.0.11"
      }
    },
    "createTime": "2024-04-04T22:39:05.674986Z",
    "updateTime": "2024-04-04T22:39:05.674986Z"
  }

Para retornar detalhes da especificação:

curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" \
  https://apihub.googleapis.com/v1/projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1

Saída:

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1",
  "displayName": "Test Version 3",
  "documentation": {},
  "specs": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec"
  ],
  "apiOperations": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/listpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/createpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/deletepet",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/getpetbyid",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/updatepet"
  ],
  "definitions": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/definitions/pet"
  ],
  "createTime": "2024-04-04T14:53:57.299213423Z",
  "updateTime": "2024-04-04T14:53:58.027321138Z"
}

Especificações da lista

Esta seção explica como listar as especificações associadas a uma versão da API.

Console

Para listar especificações com a interface:

No console do Google Cloud, acesse a página Hub de APIs.
Acesse o hub de API
Clique em APIs.
Use Filtro para especificar palavras-chave e filtrar a lista de APIs. Se necessário, use a Pesquisa para localizar uma API.
Clique em uma API para conferir os detalhes.
Na guia Versões, localize a versão que você quer inspecionar.
Selecionar uma versão
Todas as especificações vinculadas à versão são listadas na seção Arquivo de especificação.

REST

Para listar as especificações da lista associadas a uma versão da API, use a API Especificações da lista:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs"
      -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Substitua:

HUB_PROJECT: o nome do projeto host do hub da API. O projeto host foi selecionado quando o hub de API foi provisionado.
HUB_LOCATION: o local do projeto host. O local foi escolhido quando o hub da API foi provisionado.
API_ID: o ID exclusivo do recurso da API.
VERSION_ID: o ID exclusivo da versão.

Mais detalhes da especificação

Esta seção explica como obter detalhes sobre uma especificação de API associada a uma versão.

Console

Para ver detalhes de uma especificação usando a interface:

No console do Google Cloud, acesse a página Hub de APIs.
Acesse o hub de API
Clique em APIs.
Localize a API com a versão que contém a especificação que você quer inspecionar. Use Filtro para especificar palavras-chave e filtrar a lista de APIs. Se necessário, use a Pesquisa para localizar uma API.
Clique em uma API para conferir os detalhes.
Na guia Versões, localize a versão que você quer inspecionar.
Selecionar uma versão
Na seção Arquivo de especificação, selecione uma especificação para conferir os detalhes.

REST

Para conferir os detalhes de uma especificação, use a API Receber detalhes da especificação:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Substitua:

HUB_PROJECT: o nome do projeto host do hub da API. O projeto host foi selecionado quando o hub de API foi provisionado.
HUB_LOCATION: o local do projeto host. O local foi escolhido quando o hub da API foi provisionado.
API_ID: o ID exclusivo do recurso da API.
VERSION_ID: o ID exclusivo da versão.
SPEC_ID: o ID exclusivo da especificação.

Exemplo de resposta:

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec",
  "displayName": "Test Spec 1",
  "details": {
    "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.\nYou can find out more about Swagger at [https://swagger.io](https://swagger.io).",
    "openApiSpecDetails": {
      "format": "OPEN_API_SPEC_3_0",
      "version": "1.0.11"
    }
  },
  "createTime": "2024-04-04T22:39:05.098508600Z",
  "updateTime": "2024-04-04T22:39:06.661264958Z"
}

Excluir uma especificação de API

Nesta seção, explicamos como excluir a especificação de uma API de uma versão. A exclusão de uma especificação também apaga as operações associadas da versão.

Console

Para excluir recursos da API com a interface:

No console do Google Cloud, acesse a página Hub de APIs.
Acesse o hub de API
Clique em APIs.
Localize a API com a versão que contém a especificação que você quer excluir. Use Filtro para especificar palavras-chave e filtrar a lista de APIs. Se necessário, use a Pesquisa para localizar uma API.
Clique em uma API para conferir os detalhes.
Na guia Versões, localize a versão que contém a especificação que você quer excluir.
Selecione a versão.
Na seção Arquivo de especificação, selecione Excluir no menu Ações. na linha da especificação que você quer excluir.
Clique em Excluir.

REST

Para excluir um recurso de API do hub de API, use a API Excluir recurso de API:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X DELETE -H "Content-Type: application/json"

Substitua:

HUB_PROJECT: o nome do projeto host do hub da API. O projeto host foi selecionado quando o hub de API foi provisionado.
HUB_LOCATION: o local do projeto host. O local foi escolhido quando o hub da API foi provisionado.
API_ID: o ID exclusivo do recurso da API.
VERSION_ID: o ID exclusivo da versão.
SPEC_ID: o ID exclusivo da especificação a ser excluída.

Editar metadados da especificação

É possível editar alguns dos metadados associados a uma especificação armazenada no hub de API. Para conferir uma lista de metadados que podem ser editados, consulte API de patch de especificação.

Console

É possível alterar uma especificação atual no console do Google Cloud. Por exemplo, você pode mudar o nome de exibição, fazer upload de um novo arquivo de especificação, alterar o tipo de arquivo, e editar os atributos:

No console do Google Cloud, acesse a página Hub de APIs.
Acesse o hub de API
Clique em APIs.
Localize a API com a versão que contém a especificação que você quer editar. Use Filtro para especificar palavras-chave e filtrar a lista de APIs. Se necessário, use a Pesquisa para localizar uma API.
Clique em uma API para conferir os detalhes.
Na guia Versões, localize a versão que contém a especificação que você quer editar.
Selecione a versão.
Na página "Versões", localize a especificação que você quer editar.
Selecione Editar no menu Ações da linha da especificação que você quer editar.
No painel de edição de especificação, é possível mudar qualquer um dos metadados de especificação a seguir:
- Nome de exibição
- Tipo do arquivo de especificação
- Documento de especificação: procure um novo arquivo de especificação para fazer o upload.
- (Opcional) Se você quiser aplicar uma validação rígida à especificação enviada, selecione a caixa de seleção Restringir o upload do arquivo de especificações que contém erros. Quando essa opção é selecionada, uma especificação que contém erros de validação não será enviada. Por padrão, as especificações com erros são enviadas por upload.
- Atributos definidos pelo usuário (se houver)
Clique em Salvar.

REST

Para editar uma especificação com a API REST, siga estas etapas:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
    -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X PATCH -H "Content-Type: application/json"
    '{
      "display-name": DISPLAY_NAME.  # Use the request body to specify attribute changes
      "contents": {
         "contents": Base64-encoded string
         "mimeType": MIME_TYPE
      }
    }'

Substitua:

HUB_PROJECT: o nome do projeto host do hub da API. O projeto host foi selecionado quando o hub de API foi provisionado.
HUB_LOCATION: o local do projeto host. O local foi escolhido quando o hub da API foi provisionado.
API_ID: o ID exclusivo do recurso da API.
VERSION_ID: o ID exclusivo da versão.
SPEC_ID: o ID exclusivo da especificação.
Corpo da solicitação: use o corpo da solicitação para especificar os atributos que serão alterados. Consulte Definição do recurso de especificação.

Conferir os resultados de lint da especificação

O hub de API oferece um (Spectral) linter (validador) integrado que valida a especificação da OpenAPI da API. Consulte Validar as especificações da API.

No console do Google Cloud, acesse a página Hub de APIs.
Acesse o hub de API
Clique em APIs.
Localize a API com a versão que contém a especificação que você quer inspecionar. Use Filtro para especificar palavras-chave e filtrar a lista de APIs. Se necessário, use a Pesquisa para localizar uma API.
Clique em uma API para conferir os detalhes.
Na guia Versões, localize a versão que contém a especificação que você quer inspecionar.
Clique em Conferir resultados na coluna "Resultados do lint".

Acessar o conteúdo da especificação

Esse recurso permite revisar o conteúdo de uma especificação que foi enviada ao hub de API.

Console

Para ver detalhes de uma especificação usando a interface:

No console do Google Cloud, acesse a página Hub de APIs.
Acesse o hub de API
Clique em APIs.
Localize a API com a versão que contém a especificação que você quer excluir. Use Filtro para especificar palavras-chave e filtrar a lista de APIs. Se necessário, use a Pesquisa para localizar uma API.
Clique em uma API para conferir os detalhes.
Na guia Versões, localize a versão que contém a especificação que você quer inspecionar.
Clique no nome da especificação para conferir o conteúdo.

REST

A API recupera o conteúdo bruto codificado em Base64 de uma especificação de API que foi enviada ao hub da API. Use a API Receber conteúdo da especificação:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID:contents"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Substitua:

HUB_PROJECT: o nome do projeto host do hub da API. O projeto host foi selecionado quando o hub de API foi provisionado.
HUB_LOCATION: o local do projeto host. O local foi escolhido quando o hub da API foi provisionado.
API_ID: o ID exclusivo do recurso da API.
VERSION_ID: o ID exclusivo da versão.
SPEC_ID: o ID exclusivo da especificação.

Exemplo de resposta:

{
  "contents": "Base64-encoded file contents"
}