Como atualizar SmartDocs

Antes de informar o URL do portal aos usuários da API, verifique se a documentação de referência da API SmartDocs está correta e se o funcionamento da API está de acordo com a documentação. Ao revisar a documentação de referência e o teste gerados, talvez você veja algo que queira alterar.

Nesta página, você verá:

Pré-requisitos

Nesta página, presume-se que você já tenha criado seu portal.

Sobre a documentação de referência da API SmartDocs

Veja uma descrição de como adicionar gerenciamento de API nas seções:

O Endpoints Frameworks cria um documento da OpenAPI para sua API. Sempre que você implanta o documento OpenAPI no serviço do Endpoints, o SmartDocs gera a documentação de referência da API para seu portal. A IU do SmartDocs é baseada em Angular Material, uma biblioteca de componentes de IU de última geração. Os desenvolvedores podem ler a documentação de referência da API SmartDocs e usar o widget Testar esta API para interagir com a API sem sair da documentação.

Sobre os campos usados para gerar SmartDocs

Veja uma descrição de como adicionar gerenciamento de API nas seções:

Ao adicioná-lo, o Endpoints Frameworks cria um documento da OpenAPI no formato JSON para a API. Quando você implanta o documento OpenAPI (usando gcloud endpoints services deploy), o SmartDocs gera a documentação de referência atualizada da API para um portal baseado no documento OpenAPI que o Endpoints Frameworks criou.

O Endpoints Frameworks não inclui descrições no documento da OpenAPI criado para a API. Antes de fornecer o URL do portal aos usuários da API, recomendamos que você adicione descrições à API, métodos e parâmetros no documento da OpenAPI.

Se você é novo no OpenAPI, comece com o site da estrutura básica do Swagger, que fornece um documento OpenAPI de amostra e explica rapidamente cada seção do arquivo. Para informações mais detalhadas, consulte a especificação OpenAPI.

Conforme descrito na seção metadados, o valor do campo description pode conter várias linhas e é compatível com o Flavored Markdown do GitHub.

Recomendamos que você adicione um campo description à seção de parâmetros e ao corpo da solicitação para ajudar os usuários a entender como usar os métodos na API.

Seu documento OpenAPI inclui algo semelhante ao seguinte:

{
 "swagger": "2.0",
 "info": {
  "version": "1.0.0",
  "title": "example-project-12345.appspot.com"
 },
 "host": "example-project-12345.appspot.com",

No portal, os valores destes campos são exibidos como:

  • title: o valor do título é exibido na página inicial do portal na seção que lista as APIs do projeto, na página inicial da API com a palavra documentação anexada e na barra de título da API.

  • host: o valor do host, que também é o nome do serviço do Endpoints, é exibido na seção que lista as APIs do projeto na página inicial e na página Configurações na lista suspensa exibida na guia APIs.

  • version: o número da versão principal é usado no URL do portal da API.

Talvez você queira alterar o valor no campo title e adicionar um campo description para a API. Exemplo:

{
 "swagger": "2.0",
 "info": {
  "version": "1.0.0",
  "title": "Endpoints Frameworks Example",
  "description": "A simple Cloud Endpoints Frameworks API example."
 },
 "host": "example-project-12345.appspot.com",

Como regenerar SmartDocs

Para gerar a documentação de referência:

  1. Faça as alterações no arquivo openapi.json que o Endpoints Frameworks gerou.

  2. Reimplantar openapi.json:

    gcloud endpoints services deploy openapi.json

  3. Atualize a página do portal.

  4. Salve o arquivo openapi.json modificado em um local em que ele não poderá ser substituído, se você precisar gerar novamente o arquivo openapi.json posteriormente. Se você fizer alterações na API e gerar o arquivo openapi.json, será necessário mesclar as alterações no arquivo openapi.json recém-gerado com as alterações feitas anteriormente.

Veja gcloud endpoints services deploy para saber mais sobre o comando.