Documentação

Documentation fornece informações para descrever um serviço.

Por exemplo:

documentation:
  summary: >
    The Google Calendar API gives access
    to most calendar features.
  pages:
  - name: Overview
    content: (== include google/foo/overview.md ==)
  - name: Tutorial
    content: (== include google/foo/tutorial.md ==)
    subpages;
    - name: Java
      content: (== include google/foo/tutorial_java.md ==)
  rules:
  - selector: google.calendar.Calendar.Get
    description: >
      ...
  - selector: google.calendar.Calendar.Put
    description: >
      ...

A documentação é fornecida na sintaxe do Markdown. Além dos recursos padrão do Markdown, listas de definições, tabelas e blocos de código delimitados são aceitos. Os cabeçalhos de seção podem ser fornecidos e são interpretados em relação ao aninhamento de seção do contexto em que um fragmento de documentação está incorporado.

A documentação do IDL é mesclada com a documentação definida por meio da configuração no horário de normalização, onde a documentação fornecida pelas regras de configuração substitui o IDL fornecido.

Uma série de construções específicas da plataforma da API são aceitas no texto da documentação.

Para fazer referência a um elemento proto, a seguinte notação pode ser usada:

[fully.qualified.proto.name][]

Para substituir o texto de exibição usado no link, é possível usar o seguinte:

[display text][fully.qualified.proto.name]

O texto pode ser excluído do documento por meio da seguinte notação:

(-- internal comment --)

Algumas diretrizes estão disponíveis na documentação. Observe que as diretrizes precisam aparecer em uma única linha para serem devidamente identificadas. A diretiva include inclui um arquivo do Markdown de uma fonte externa:

(== include path/to/file ==)

A diretriz resource_for marca uma mensagem para ser o recurso de uma coleção na visualização REST. Se não for especificada, as ferramentas tentam inferir o recurso das operações em uma coleção:

(== resource_for v1.shelves.books ==)

A diretiva suppress_warning não afeta diretamente a documentação e é documentada em conjunto com a validação da configuração do serviço.

Representação JSON 

{
  "summary": string,
  "pages": [
    {
      object(Page)
    }
  ],
  "rules": [
    {
      object(DocumentationRule)
    }
  ],
  "documentationRootUrl": string,
  "overview": string
}
Campos
summary

string

Um breve resumo do que o serviço faz. Só pode ser fornecido por texto simples.

pages[]

object(Page)

As páginas de nível superior do conjunto de documentação.

rules[]

object(DocumentationRule)

Uma lista de regras de documentação que se aplicam a elementos individuais da API.

OBSERVAÇÃO: todas as regras de configuração do serviço seguem a ordem "vale a última opção".
documentationRootUrl

string

O URL para a raiz da documentação.

overview

string

Declara uma única página de visão geral. Por exemplo:


documentation:
  summary: ...
  overview: (== include overview.md ==)

Este é um atalho para a seguinte declaração (usando estilo de páginas):


documentation:
  summary: ...
  pages:
  - name: Overview
    content: (== include overview.md ==)

Observação: não é possível especificar os campos overview e pages.

Página

Representa uma página da documentação. Uma página pode conter subpáginas para representar uma estrutura de conjunto de documentação aninhada.

Representação JSON 

{
  "name": string,
  "content": string,
  "subpages": [
    {
      object(Page)
    }
  ]
}
Campos
name

string

O nome da página. Ele será usado como identificador da página para gerar o URI da página, o texto do link para esta página na navegação etc. O nome completo da página (a partir do nome da página raiz para esta página, concatenado com .) pode ser usado como referência para a página na sua documentação. Por exemplo:


pages:
- name: Tutorial
  content: (== include tutorial.md ==)
  subpages:
  - name: Java
    content: (== include tutorial_java.md ==)

Você pode fazer referência à página Java por meio da sintaxe do link de referência do Markdown: [Java][Tutorial.Java].
content

string

O conteúdo do Markdown da página. Você pode usar

(== include {path} ==)

para incluir conteúdo de um arquivo do Markdown.
subpages[]

object(Page)

Subpáginas desta página. A ordem das subpáginas especificadas aqui será herdada no docset gerado.

DocumentationRule

Uma regra de documentação fornece informações sobre elementos individuais da API.

Representação JSON 

{
  "selector": string,
  "description": string,
  "deprecationDescription": string
}
Campos
selector

string

O seletor é uma lista de padrões separada por vírgulas. Cada padrão é um nome qualificado do elemento que pode terminar em "*", indicando um curinga. Os caracteres curinga só são permitidos no final e para um componente completo do nome qualificado. Por exemplo, "foo.*" é aceito, mas "foo.b*" ou "foo.*.bar" não. Para especificar um padrão para todos os elementos aplicados, o padrão "*" é usado.

description

string

Descrição das APIs selecionadas.

deprecationDescription

string

Descrição de suspensão do uso dos elementos selecionados. Pode ser fornecida se um elemento for marcado como deprecated.