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á:

  • a documentação de referência da API SmartDocs;
  • como o SmartDocs usa os campos em seu documento OpenAPI para gerar SmartDocs;
  • como regenerar SmartDocs.
Para a conclusão de cada tarefa, são fornecidos os papéis mínimos exigidos do Identity and Access Management. 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

Toda vez que você implanta um documento OpenAPI no seu serviço do Endpoints, o SmartDocs gera documentação de referência da API para o seu portal. A IU do SmartDocs é baseada em Angular Material, uma biblioteca de componentes de IU de última geração. Os desenvolvedores podem analisar a documentação de referência da API SmartDocs e usar o painel Testar esta API para interagir com ela sem sair da respectiva documentação.

Sobre os campos usados para gerar o SmartDocs

O documento do OpenAPI inclui algo semelhante ao seguinte:

swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "echo-api.endpoints.example-project-12345.cloud.goog"

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.

  • description: o valor para a descrição é exibido sob o título, com uma fonte menor, na página inicial 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.

O portal do Endpoints cria a documentação de referência para cada endpoint individual listado na seção paths do documento da OpenAPI. Os trechos a seguir são do documento da OpenAPI usado para gerar a documentação de referência para o endpoint echo na API Endpoints Example na demonstração do Portal do Endpoints:

paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      security:
      - api_key: []

O parâmetro para o endpoint echo é definido na seguinte seção: 

definitions:
  echoMessage:
    type: "object"
    properties:
      message:
        type: "string"

O arquivo openapi.yaml completo usado na demonstração do portal do Endpoints está na amostra getting-started do Endpoints.

Como prática recomendada, sempre inclua o campo description nas definições de propriedade e em todas as outras seções do documento do OpenAPI. O campo description pode conter várias linhas e é compatível com o Markdown personalizado para o GitHub. Por exemplo, a seguinte linha cria uma lista com marcadores na página inicial da API no portal:

swagger: "2.0"
info:
  description: "A simple API to help you learn about Cloud Endpoints.

  * item 1

  * item 2"
title: "Endpoints Example"
  version: "1.0.0"
host: "echo-api.endpoints.example-project-12345.cloud.goog"

Como gerar o SmartDocs novamente

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

  1. Faça alterações no documento do OpenAPI.

  2. Reimplante o documento da OpenAPI (referido como openapi.yaml no seguinte comando):

    gcloud endpoints services deploy openapi.yaml

  3. Atualize a página do portal.

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