Dokumentation

Documentation liefert Informationen zur Beschreibung eines Dienstes.

Beispiel:

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

Die Dokumentation wird in der Markdown-Syntax bereitgestellt. Zusätzlich zu den standardmäßigen Markdown-Funktionen werden Definitionslisten, Tabellen und umzäunte Codeblöcke unterstützt. Abschnittsüberschriften können bereitgestellt werden und werden relativ zur Abschnittsverschachtelung des Kontexts interpretiert, in den ein Dokumentationsfragment eingebettet ist.

Die Dokumentation aus der IDL wird mit der über die Konfiguration definierten Dokumentation zur Normalisierungszeit zusammengeführt, wobei die durch die Konfigurationsregeln bereitgestellte Dokumentation die bereitgestellte IDL überschreibt.

Eine Reihe von Konstrukten, die für die API-Plattform spezifisch sind, werden im Dokumentationstext unterstützt.

Folgende Notation kann verwendet werden, um auf ein Proto-Element Bezug zu nehmen:

[fully.qualified.proto.name][]

Das kann verwendet werden, um den Anzeigetext für den Link zu überschreiben:

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

Text kann mit folgender Schreibweise aus dem Dokument ausgeschlossen werden:

(-- internal comment --)

Einige Anweisungen sind in der Dokumentation verfügbar. Beachten Sie, dass die Anweisungen in einer einzigen Zeile angezeigt werden müssen, damit sie richtig identifiziert werden können. Die Anweisung include enthält eine Markdown-Datei von einer externen Quelle:

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

Die Anweisung resource_for markiert in der REST-Ansicht die Nachricht als Ressource einer Sammlung. Wenn sie nicht angegeben wird, versuchen Tools, die Ressource aus den Vorgängen in eine Auflistung abzuleiten:

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

Die Anweisung suppress_warning wirkt sich nicht direkt auf die Dokumentation aus und wird gemeinsam mit der Validierung der Dienstkonfiguration dokumentiert.

JSON-Darstellung 

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

string

Eine kurze Zusammenfassung dessen, was der Dienst bietet. Kann nur im Klartext bereitgestellt werden.

pages[]

object(Page)

Die Seiten auf oberster Ebene für die Dokumentation.

rules[]

object(DocumentationRule)

Eine Liste mit Dokumentationsregeln, die für einzelne API-Elemente gelten.

HINWEIS: Alle Dienstkonfigurationsregeln befolgen die Reihenfolge "last one wins" (der Letzte gewinnt).
documentationRootUrl

string

Die URL zum Dokumentationsstammverzeichnis.

overview

string

Deklariert eine einzelne Übersichtsseite. Beispiel:


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

Dies ist ein Kurzbefehl für die folgende Deklaration (mit dem Seitenformat):


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

Hinweis: Sie können nur das Feld overview oder pages festlegen.

Page (Seite)

Stellt eine Dokumentationsseite dar. Eine Seite kann Unterseiten enthalten, die die Struktur der verschachtelten Dokumentationsgruppen darstellen.

JSON-Darstellung 

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

string

Der Name der Seite. Sie wird als Identität der Seite verwendet, um den URI der Seite, den Text für den Link, der zu dieser Seite führt usw., zu generieren. Der vollständige Seitenname (beginnend mit dem Namen der Stammseite bis zu dieser Seite, die mit . verkettet ist) kann dazu dienen, auf die Seite in Ihrer Dokumentation zu verweisen. Beispiel:


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

Sie können auf die Seite Java mithilfe der Syntax für Markdown-Referenzlinks verweisen: [Java][Tutorial.Java].
content

string

Der Markdown-Inhalt der Seite. Sie können Folgendes eingeben:

(== include {path} ==)

um Inhalte aus einer Markdown-Datei miteinzubeziehen.
subpages[]

object(Page)

Unterseiten dieser Seite. Die Reihenfolge der hier angegebenen Unterseiten wird in der generierten Dokumentation berücksichtigt.

DocumentationRule (Dokumentationsregel)

Eine Dokumentationsregel enthält Informationen zu einzelnen API-Elementen.

JSON-Darstellung 

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

string

Die Auswahl ist eine kommagetrennte Liste von Mustern. Jedes Muster ist ein qualifizierter Name des Elements, das mit "*" enden kann und einen Platzhalter angibt. Platzhalter sind nur am Ende und für eine ganze Komponente des qualifizierten Namens erlaubt, d. h. "foo.*" ist zulässig, aber "foo.b *" oder "foo.*.bar" nicht. Um einen Standardwert für alle zutreffenden Elemente festzulegen, wird das gesamte Muster "*" verwendet.

description

string

Beschreibung der ausgewählten API(s).

deprecationDescription

string

Gültigkeitsbeschreibung der ausgewählten Elemente. Sie kann angegeben werden, wenn ein Element als deprecated gekennzeichnet ist.