Documentação

Nesta seção, são apresentadas diretrizes para adicionar documentação in-line à sua API. A maioria das APIs também terá visões gerais, tutoriais e documentação de referência de nível superior, que estão fora do escopo deste Guia de projeto. Para mais informações sobre a nomenclatura de APIs, recursos e métodos, consulte Convenções de nomenclatura.

Formato dos comentários

Adicione comentários ao seu arquivo .proto utilizando o formato comum de comentário de Buffers do protocolo //.

// Creates a shelf in the library, and returns the new Shelf.
rpc CreateShelf(CreateShelfRequest) returns (Shelf) {
  option (google.api.http) = { post: "/v1/shelves" body: "shelf" };
}

Comentários na configuração do serviço

Como alternativa para adicionar comentários de documentação ao arquivo .proto, você pode adicionar a documentação in-line à API no arquivo de configuração do serviço YAML dela. A documentação neste arquivo terá precedência sobre aquela no seu .proto se o mesmo elemento estiver documentado em ambos os arquivos.

documentation:
  summary: Gets and lists social activities
  overview: A simple example service that lets you get and list possible social activities
  rules:
  - selector: google.social.Social.GetActivity
    description: Gets a social activity. If the activity does not exist, returns Code.NOT_FOUND.
...

Talvez você precise usar essa abordagem se tiver vários serviços que usem os mesmos arquivos .proto e quiser fornecer uma documentação específica de um serviço. As regras de documentação do YAML também permitem adicionar uma overview mais detalhada à descrição da API. No entanto, em geral, a adição de comentários de documentação ao .proto tem preferência.

Como ocorre com os comentários .proto, você pode usar o Markdown para fornecer outras formatações nos comentários do arquivo YAML.

Descrição de APIs

A descrição da API é uma frase que começa com um verbo ativo que descreve o que você pode fazer com a API. No arquivo .proto, uma descrição da API é adicionada como um comentário ao service correspondente, como no exemplo a seguir:

// Manages books and shelves in a simple digital library.
service LibraryService {
...
}

Veja abaixo mais algumas descrições da API de exemplo:

  • Compartilha atualizações, fotos, vídeos e muito mais com seus amigos em todo o mundo.
  • Acessa um serviço de aprendizado de máquina hospedado na nuvem que facilita a criação de aplicativos inteligentes que respondem a streams de dados.

Descrição de recursos

Uma descrição de recurso é uma frase parcial que descreve o que o recurso representa. Se você precisar adicionar mais detalhes, use frases extras. No seu arquivo .proto, uma descrição de recurso é adicionada como um comentário ao tipo de mensagem correspondente, como no exemplo a seguir:

// A book resource in the Library API.
message Book {
  ...
}

Veja abaixo alguns exemplos de descrições de recursos:

  • Uma tarefa na lista de afazeres do usuário. Cada tarefa tem uma prioridade única.
  • Um evento no calendário do usuário.

Descrições de parâmetros e campos

Uma frase nominal que descreve uma definição de campo ou parâmetro, conforme mostrado nos exemplos a seguir:

  • O número de tópicos desta série.
  • A precisão das coordenadas de latitude e longitude, em metros. Não podem ser negativas.
  • Uma sinalização que regula se os valores de URL de anexos são retornados para recursos de envio nesta série. O valor padrão para series.insert é true.
  • O contêiner para informações de votação. Presente somente quando as informações de votação são registradas.
  • Atualmente não usado ou obsoleto.

Descrições de parâmetros e campos

  • Precisam descrever claramente os limites (isto é, serem claras sobre o que é válido ou não. Lembre-se de que os engenheiros farão o melhor que puderem para não interromper nenhum serviço e não poderão ler o código subjacente para esclarecer informações confusas).
  • Precisam especificar qualquer valor ou comportamento padrão. Em outras palavras, o que o servidor fará se nenhum valor for fornecido.
  • Se forem de uma string, como um nome ou caminho, descrevem a sintaxe e listam os caracteres permitidos e qualquer codificação necessária. Exemplo:
    • De 1 a 255 caracteres no conjunto [A-a0-9]
    • Uma string de caminho de URL válido que começa com / que segue as convenções da RFC 2332. O comprimento máximo é de 500 caracteres.
  • Devem fornecer um exemplo de valor sempre que possível.
  • Se o valor do campo for obrigatório, somente entrada, somente saída, ele precisará ser documentado no início da descrição do campo. Por padrão, todos os campos e parâmetros são opcionais. Exemplo:
message Table {
  // Required. The resource name of the table.
  string name = 1;
  // Input only. Whether to dry run the table creation.
  bool dryrun = 2;
  // Output only. The timestamp when the table was created. Assigned by
  // the server.
  Timestamp create_time = 3;
  // The display name of the table.
  string display_name = 4;
}

Descrição de métodos

A descrição de um método é uma frase que indica o efeito que o método tem e em qual recurso ele opera. Geralmente, começa com um verbo no presente e na terceira pessoa do singular. Se você precisar adicionar mais detalhes, use frases extras. Veja alguns exemplos:

  • Lista os eventos do calendário para o usuário autenticado.
  • Atualiza um evento do calendário com os dados incluídos na solicitação.
  • Exclui um registro do histórico de localização do usuário autenticado.
  • Cria ou atualiza um registro no histórico de localização do usuário autenticado usando os dados incluídos na solicitação. Se já houver um recurso de localização com o mesmo valor do carimbo de data/hora, os dados fornecidos substituirão os dados existentes.

Lista de verificação para todas as descrições

Deixe a descrição breve, mas completa, de modo que possa ser compreendida por usuários que não tenham mais informações sobre a API. Na maioria dos casos, há mais a dizer do que apenas reafirmar o óbvio, por exemplo, a descrição do método series.insert não pode apenas dizer "Insere uma série". A nomenclatura será informativa, mas a maioria dos leitores está lendo suas descrições porque quer mais informações do que os nomes oferecem. Se você não tem certeza do que mais dizer em uma descrição, tente responder a todas as questões relevantes a seguir:

  • Do que se trata?
  • O que acontece se funcionar? O que acontece se falhar? O que pode fazer com que ele falhe e como?
  • É idempotente?
  • Quais são as unidades? (Exemplos: medidores, graus, pixels).
  • Qual o intervalo de valores que ele aceita? O intervalo é inclusivo ou exclusivo?
  • Quais são os efeitos colaterais?
  • Como se usa?
  • Quais são os erros comuns que podem ocasionar a interrupção dele?
  • Está sempre presente? (Por exemplo: "contêiner para informações de votação". Presente apenas quando as informações de votação são registradas").
  • Tem uma configuração padrão?

Convenções

Nesta seção, são listadas algumas convenções de uso para descrições e documentação textual. Por exemplo, use "ID" (todas as letras maiúsculas), em vez de "Id" ou "id" quando se fala sobre identificadores. Use "JSON" em vez de "Json" ou "json" ao se referir a esse formato de dados. Mostre todos os nomes de campos/parâmetros em code font. Coloque valores de string literal em code font e entre aspas.

  • ID
  • JSON
  • RPC
  • REST
  • property_name ou "string_literal"
  • true/false

Níveis de requisitos

Para definir expectativas ou níveis de requisitos de estado, use os termos: precisa, não pode, obrigatório, deverá, não deverá, deve, não deve, recomendado, pode e opcional.

Os significados são definidos na RFC 2119. É bom incluir a declaração do resumo da RFC na documentação da sua API.

Determine qual termo atende aos seus requisitos e ofereça flexibilidade aos desenvolvedores. Não use termos absolutos como precisa quando outras opções funcionam tecnicamente em sua API.

Estilo de linguagem

Como em nossas convenções de nomenclatura, recomendamos usar vocabulário e estilo simples e consistentes ao escrever comentários em documentos. Os comentários devem ser compreensíveis para leitores que não são falantes nativos do português, então evite jargões, gírias, metáforas complexas, referências de cultura pop ou algo que não seja traduzido facilmente. Use um estilo amigável e profissional que fale diretamente com os desenvolvedores que leem seus comentários e mantenha tudo o mais conciso possível. Lembre-se, a maioria dos leitores quer descobrir como fazer algo com sua API, e não ler sua documentação!

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…