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á:- a documentação de referência da API SmartDocs;
- Como os SmartDocs usa os campos no arquivo
openapi.json
criado pelo Cloud Endpoints Frameworks para gerar SmartDocs - Como regenerar SmartDocs. Para a conclusão de cada tarefa, são fornecidos os papéis mínimos exigidos de gerenciamento de identidade e acesso. Para mais informações sobre as permissões do IAM, consulte o seguinte:
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:
Faça as alterações no arquivo
openapi.json
que o Endpoints Frameworks gerou.Reimplantar
openapi.json
:gcloud endpoints services deploy openapi.json
Atualize a página do portal.
Salve o arquivo
openapi.json
modificado em um local em que ele não poderá ser substituído, se você precisar gerar novamente o arquivoopenapi.json
posteriormente. Se você fizer alterações na API e gerar o arquivoopenapi.json
, será necessário mesclar as alterações no arquivoopenapi.json
recém-gerado com as alterações feitas anteriormente.
Veja gcloud endpoints services deploy
para saber mais sobre o comando.