Documentação da API Inline

Esta seção fornece diretrizes para adicionar documentação in-line à 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 design. Para mais informações sobre a nomenclatura de APIs, recursos e métodos, consulte Convenções de nomenclatura.

Formato dos comentários em arquivos proto

Adicione comentários ao arquivo .proto usando o formato de comentário normal de buffers de 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 à adição de 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. A documentação neste arquivo terá precedência sobre a documentação no .proto se o mesmo elemento estiver documentado nos dois 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 seja necessário usar essa abordagem se você tiver vários serviços que usam os mesmos arquivos .proto e quiser fornecer documentação específica do serviço. As regras de documentação do YAML também permitem adicionar overview à descrição da API. No entanto, em geral, é preferível adicionar comentários da documentação ao .proto.

Assim como nos comentários do .proto, você pode usar o Markdown para fornecer formatação adicional 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 à 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 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 descontinuado.

As descrições de campos e parâmetros precisam descrever quais valores são válidos e inválidos. 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.

Para strings, a descrição precisa descrever a sintaxe e os caracteres permitidos, bem como 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.

A descrição precisa especificar qualquer valor ou comportamento padrão, mas pode omitir valores padrão que são efetivamente nulos.

Se o valor do campo for obrigatório, somente entrada, somente saída, ele precisa 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 validate table creation without actually doing it.
  bool validate_only = 2;

  // Output only. The timestamp when the table was created. Assigned by
  // the server.
  google.protobuf.Timestamp create_time = 3;

  // The display name of the table.
  string display_name = 4;
}

Observação: as descrições de campo precisam fornecer um valor de exemplo sempre que possível e útil.

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, ela começa com um verbo no presente e na terceira pessoa do singular. Por exemplo: caminha, corre. Se você precisar adicionar mais detalhes, use outras frases. 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 local com o mesmo valor de carimbo de data/hora, os dados fornecidos vão substituir os atuais.

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

Certifique-se de que cada descrição seja breve, mas completa, e possa ser compreendida pelos usuários que não têm informações adicionais 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 deve dizer apenas "Insere uma série." Embora a nomenclatura precise ser informativa, a maioria dos leitores está lendo suas descrições porque querem mais informações do que os próprios nomes. 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. Mostrar todos os nomes de campos e parâmetros em code font. Coloque valores de string literal em code font e 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!