Como adicionar uma documentação personalizada

OpenAPI | gRPC

A partir de 21 de março de 2022, o Portal do Cloud Endpoints vai ser descontinuado. O Portal do Cloud Endpoints não estará mais disponível após 21 de março de 2023. O tráfego da API gerenciado pelo Cloud Endpoints não é afetado por essa mudança. Para mais informações, consulte Descontinuação de recursos.

Além da documentação de referência da API SmartDocs, é possível adicionar documentação personalizada ao portal necessário para os usuários da API. Mesmo que você não precise fornecer a seus usuários mais páginas de documentação, será necessário atualizar o guia de primeiros passos de exemplo exibido no portal para explicar como começar a usar sua API.

Nesta página, você verá como alterar o guia de exemplo Primeiros passos, além de como criar e exibir páginas de documentação adicionais no seu portal. 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:

• Como entender os papéis
• Como conceder, alterar e revogar acesso a recursos
• Como criar e gerenciar papéis personalizados

Pré-requisitos

Nesta página, presume-se que você:

• tenha criado seu portal;
• instalou e inicializou a Google Cloud CLI;
• tenha instalado o Git;
• tenha definido o nome e o e-mail do Git.

Sobre a documentação personalizada

Para exibir a documentação personalizada em seu portal, armazene os arquivos em um repositório Git e configure o URL para o repositório Git na página Configurações em seu portal. É possível adicionar os arquivos da sua documentação personalizada em:

• um repositório particular no Cloud Source Repositories que esteja no mesmo projeto do Google Cloud que a API;
• Um repositório público no GitHub ou no Bitbucket.

Para que o Portal do Cloud Endpoints encontre e exiba sua documentação personalizada, os arquivos e as pastas no seu repositório precisam ter uma estrutura específica. Na raiz do repositório, você precisa de uma pasta com o nome do serviço do Cloud Endpoints. É possível criar mais subpastas conforme o necessário. A barra de navegação à esquerda contém links para suas pastas e arquivos. Para mais informações, consulte Estrutura de diretório exigida.

Para editar o conteúdo no guia de primeiros passos e escrever o conteúdo das páginas de documentação adicionais, use o Markdown. O portal do Endpoints segue a especificação CommonMark, além da extensão de tabela da especificação Flavored Markdown do GitHub (links em inglês).

Também é possível adicionar imagens ao repositório e referenciá-las dos arquivos do Markdown.

Primeiros passos para atualizar a documentação personalizada

Para ajudar você a dar os primeiros passos, recomendamos clonar o repositório endpoints-developer-portal-sample-content (em inglês) no GitHub, que contém os arquivos a seguir:

• Getting Started.md: o arquivo Markdown com o conteúdo da página Primeiros passos de exemplo que é exibida no seu portal.
• Example Page.md: um arquivo de exemplo para ajudar você a usar Markdown.
• navigation.yaml: um arquivo que descreve a ordem das páginas e pastas na barra de navegação à esquerda do portal.

• add_example_page: um script que faz o seguinte:

  • Cria um repositório Git no Cloud Source Repositories no seu projeto do Google Cloud.
  • Cria um repositório Git local na pasta default-content-repo.
  • Cria uma pasta com o mesmo nome do serviço do Endpoints e uma subpasta chamada Guides.
  • Adiciona arquivos chamados Example Page.md e Getting Started.md à pasta Guides.
  • Adiciona Example Page ao arquivo navigation.yaml.
  • Valida e envia essas alterações para o repositório Git recém-criado no Cloud Source Repositories.

  Há duas versões do script:

  • add_example_page.sh (shell bash) para usuários do Linux e do Mac
  • add_example_page.ps1 (PowerShell) para usuários do Windows

  A execução do script é opcional. Como alternativa, crie manualmente um repositório no Cloud Source Repositories ou use um repositório público do GitHub ou do Bitbucket. É necessário configurar a estrutura do diretório exigida para sua documentação personalizada.

  Antes de executar o script, confira a documentação de Preços e cotas do Cloud Source Repositories. Se você executar o script e depois optar por usar um repositório público do GitHub ou do Bitbucket, será possível excluir o repositório do Cloud Source Repositories.

Receber os arquivos de início da documentação personalizada

Veja nesta seção a configuração necessária para executar o script add_example_page.

Permissões exigidas para a tarefa

Para executar essa tarefa, você precisa ter o papel Editor do projeto no projeto. Esse papel tem a permissão necessária para:

• Ativar a API do Cloud Source Repositories.
• Criar o repositório no Cloud Source Repositories.
• Sincronizar o conteúdo do repositório com o portal da sua API.

Para conseguir os arquivos de início da documentação personalizada, siga estas etapas:

1. Ative a API do Cloud Source Repositories:

   1. Em APIs e serviços, acesse a página Biblioteca de APIs.

      Acessar a Biblioteca de APIs

   2. Na lista de projetos, selecione o projeto em que está sua API.

   3. Procure a API Cloud Source Repositories e clique no cartão dela para que a página de informações seja exibida.

   4. Selecione Ativar.

2. Verifique se a CLI gcloud está autorizada a acessar seus dados e serviços:

   gcloud auth login
   

3. Defina o projeto padrão. No comando a seguir, substitua YOUR_PROJECT_ID pelo ID do projeto do Google Cloud em que você criou a API do Endpoints:

   gcloud config set project YOUR_PROJECT_ID
   

4. Faça o download dos scripts, da configuração e do conteúdo de amostra:

   git clone https://github.com/GoogleCloudPlatform/endpoints-developer-portal-sample-content
   

5. Acesse o diretório que contém o script:

   cd endpoints-developer-portal-sample-content/scripts
   

6. Exiba seu nome de serviço do Endpoints:

   gcloud endpoints services list
   

7. Execute o script com o nome do serviço do Endpoints:

   • Usuários do Linux e Mac: ./add_example_page.sh SERVICE_NAME
   • Usuários do Windows: add_example_page.ps1 SERVICE_NAME

   Quando o script é concluído, ele imprime URLs nos locais a seguir:

   • As configurações do portal da sua API.

   • Seu URL do Git. Esse é o mesmo URL exibido no campo Clone URL na página do Cloud Source Repositories.

8. Sincronize o repositório para o portal:

   1. Destaque e copie o primeiro URL e cole-o na barra de endereço do seu navegador para acessar a página Configurações.
   2. Siga as instruções de login para acessar a página Configurações da sua API. Se você tiver mais de uma conta, escolha a que está no projeto do Google Cloud que é proprietário da API.
   3. Destaque e copie o URL clone do seu repositório Git e cole-o no campo Configurações do conteúdo personalizado.
   4. Clique em Sincronizar.
   5. Clique em Save.
   6. Clique na barra de título para voltar à página inicial da documentação da API.

   Na barra de navegação à esquerda, clique em Página de exemplo para exibir o conteúdo.

9. Navegue pelo conteúdo do seu repositório recém-criado. No Console do Google Cloud, acesse a página Source Repositories > Código-fonte do seu projeto.

   Acesse o navegador do código-fonte

   O navegador do código-fonte mostra uma visualização do diretório do conteúdo do repositório no nível de commit mais recente. Consulte Repositórios de navegação para mais informações.

Como modificar a documentação personalizada

Agora que você tem uma documentação personalizada no Cloud Source Repositories, é possível modificar o conteúdo e adicionar ou excluir arquivos e pastas conforme o necessário. Se você não se sente familiarizado com o Git, a documentação dele contém a documentação de referência, bem como links para livros e vídeos.

Permissões exigidas para a tarefa

Para executar essa tarefa, você precisa ter o papel Editor do projeto no projeto. Esse papel tem a permissão necessária para:

• Modificar o conteúdo no Cloud Source Repositories
• Sincronizar o conteúdo do repositório com o portal da sua API.

Modificar o conteúdo de Getting Started

Para modificar o conteúdo de Getting Started, siga estas etapas:

1. Começando na raiz do repositório Git local, vá para a pasta que tem o mesmo nome do serviço do Endpoints. Exemplo:

   cd example-api.example.com
   

2. Vá para a pasta que contém Getting Started.md:

   cd Guides
   

3. Abra Getting Started.md em um editor de texto.

4. Modifique o conteúdo conforme necessário para ajudar os usuários a começarem a usar sua API.

5. Salve o arquivo.

6. Confirme as mudanças:

   git commit -a -m "updated getting started"
   

7. Envie as alterações para seu repositório no Cloud Source Repositories:

   git push
   

8. Sincronize o conteúdo atualizado no seu portal:

   1. Navegue até o portal.
   2. Clique em Configurações.
   3. Na página Configurações, clique na guia APIs e selecione sua API na lista.
   4. Clique em Sincronizar.
   5. Clique em Save.

   Ao clicar no link Primeiros passos na barra de navegação à esquerda, você verá o conteúdo atualizado no Portal do Endpoints.

Remover Example Page

Para remover Example Page, siga estas etapas:

1. Começando na raiz do repositório Git local, vá para a pasta que tem o mesmo nome do serviço do Endpoints. Exemplo:

   cd example-api.example.com
   

2. Abra o arquivo navigation.yaml em um editor de texto.

3. Na seção ordering, exclua a linha com Example Page.

4. Salve o arquivo.

5. Remova o arquivo Example Page.md do Git:

   git rm ‘Guides/Example Page.md'
   

6. Confirme as mudanças:

   git commit -a -m "removed example page"
   

7. Envie as alterações para seu repositório no Cloud Source Repositories:

   git push
   

8. Sincronize o conteúdo atualizado no seu portal:

   1. Navegue até o portal.
   2. Clique em Configurações.
   3. Na página Configurações, clique na guia APIs e selecione sua API na lista.
   4. Clique em Sincronizar.
   5. Clique em Save.

Example Page não estará mais na barra de navegação à esquerda.

Renomear Example Page

Para renomear Example Page, siga estas etapas:

1. Começando na raiz do repositório Git local, vá para a pasta que tem o mesmo nome do serviço do Endpoints. Exemplo:

   cd example-api.example.com
   

2. Abra o arquivo navigation.yaml em um editor de texto.

3. Na seção ordering, altere Página de exemplo para o título do seu guia. O nome precisa corresponder ao do arquivo real no diretório Guides.

4. Salve o arquivo.

5. Renomeie o arquivo Example Page.md no Git.

   git mv 'Guides/Example Page.md' 'Guides/NEW FILENAME.md'

6. Modifique o conteúdo do arquivo renomeado, conforme necessário.

7. Confirme as mudanças:

   git commit -a -m "removed example page"
   

8. Envie as alterações para seu repositório no Cloud Source Repositories:

   git push
   

9. Sincronize o conteúdo atualizado no seu portal:

   1. Navegue até o portal.
   2. Clique em Configurações.
   3. Na página Configurações, clique na guia APIs e selecione sua API na lista.
   4. Clique em Sincronizar.
   5. Clique em Save.

A página renomeada será exibida na barra de navegação à esquerda.

Estrutura de diretório obrigatória

Para que o Portal do Endpoints encontre e exiba seu conteúdo personalizado, os arquivos e as pastas no seu repositório precisam estar em uma estrutura específica.

Na raiz do repositório, é necessário que haja uma pasta com seu nome de serviço do Endpoints. Essa estrutura oferece a opção de usar um repositório para várias APIs por meio de pastas separadas no nível raiz para cada API.

As subpastas da pasta de serviços permitem que você agrupe páginas relacionadas em uma seção e podem conter outras subpastas. O título das pastas e os nomes de arquivos são usados na navegação. Por exemplo, um arquivo chamado Getting Started.md aparece na barra de navegação esquerda como Getting Started. Dentro da pasta com o nome do seu serviço do Endpoints, deve haver um arquivo chamado navigation.yaml. Esse arquivo indica como você quer que seu conteúdo apareça na barra de navegação à esquerda em seu portal. O padrão é este:

ordering:
- Introduction
- Guides
- API Reference
- Resources

folders:
  Guides:
    ordering:
    - Getting Started
    - Example Page

A primeira lista ordering especifica a ordem em que você quer que as entradas sejam exibidas naquele nível. Por exemplo, o arquivo navigation.yaml padrão especifica que a página Introduction aparece primeiro, seguida pela seção Guides e assim por diante.

Introduction, API Reference e Resources são seções especiais. Você não deve removê-las de navigation.yaml, mas pode alterar a ordem delas.

Todas as pastas e páginas precisam ter uma configuração correspondente na configuração de folders pai em navigation.yaml. Se omitida, a página ou pasta não aparecerá no portal. Por exemplo, no arquivo padrão navigation.yaml, a chave folders contém uma subchave chamada Guides porque há uma pasta com o mesmo nome.

Adicionar imagens

É possível adicionar imagens ao repositório Git de conteúdo personalizado e fazer referência a elas em arquivos Markdown. Se você colocar as imagens e qualquer arquivo Markdown que faça referência a elas no mesmo diretório do nome do serviço do Endpoints, será possível referenciar as imagens com um URL relativo que começa com /.

Por exemplo, suponha que você tenha a seguinte estrutura de diretórios:

~/example-api.example.com/
    get-started.md
    images/
        example.jpg

É possível adicionar a imagem images/example.jpg a get-started.md com a marcação a seguir:

    ![alt-text](/images/example.jpg "Optional title")

É possível adicionar imagens hospedadas em outro lugar usando a sintaxe Markdown padrão e o URL completo da imagem:

    ![alt-text](https://example.com/image.png "Optional title")

O portal é compatível com os tipos de imagem:

• BMP
• GIF
• JPEG
• PNG
• TIFF
• WEBP

Limites de conteúdo personalizados

O portal tem as seguintes limitações no conteúdo personalizado:

• máximo de 200 páginas Markdown por API
• máximo de 200 imagens por API
• tamanho máximo de 4 MiB por imagem

A seguir

• Como sincronizar a documentação personalizada por meio de uma API
• Como atualizar a documentação de referência da API SmartDocs