Inline-Dokumentation zur API

Dieser Abschnitt enthält Richtlinien zum Hinzufügen einer Inline-Dokumentation zu Ihrer API. Die meisten APIs haben außerdem Übersichten, Lernprogramme und Referenzdokumentationen auf höherer Ebene, die außerhalb des Geltungsbereichs dieses Entwurfshandbuchs liegen. Weitere Informationen zur Benennung von APIs, Ressourcen und Methoden finden Sie in den Namenskonventionen.

Format von Kommentaren in Proto-Dateien

Fügen Sie Ihrer .proto-Datei Kommentare mit dem üblichen //-Kommentarformat der Protokollpuffer hinzu.

// 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" };
}

Kommentare in der Dienstkonfiguration

Als Alternative zum Hinzufügen von Dokumentationskommentaren zu Ihrer .proto - Datei können Sie Ihrer API eine Inline-Dokumentation in der YAML-Dienstkonfigurationsdatei hinzufügen. Die Dokumentation in dieser Datei hat Vorrang vor der Dokumentation in .proto, wenn dasselbe Element in beiden Dateien dokumentiert ist.

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

Dieser Ansatz ist möglicherweise erforderlich, wenn dieselben .proto-Dateien verwendet werden und Sie eine dienstspezifische Dokumentation zur Verfügung stellen möchten. Mit YAML-Dokumentationsregeln können Sie Ihrer API-Beschreibung auch ein detaillierteres overview hinzufügen. Im Allgemeinen empfiehlt es sich jedoch, Dokumentationskommentare zu Ihrem .proto hinzuzufügen.

Wie bei .proto-Kommentaren können Sie Markdown verwenden, um zusätzliche Formatierungen in Ihren YAML-Dateikommentaren bereitzustellen.

API-Beschreibung

Die API-Beschreibung ist eine Wortgruppe, die mit einem aktiven Verb beginnt und beschreibt, was Sie mit der API tun können. In der Datei .proto wird dem entsprechenden service wie im folgenden Beispiel eine API-Beschreibung als Kommentar hinzugefügt:

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

Hier ein paar weitere Beispiele von API-Beschreibungen:

• Teilt Aktualisierungen, Fotos, Videos und vieles mehr mit Ihren Freunden auf der ganzen Welt.
• Ruft einen in der Cloud gehosteten maschinellen Lerndienst auf, der das Erstellen intelligenter Anwendungen erleichtert, die auf Datenströme reagieren.

Ressourcenbeschreibung

Eine Ressourcenbeschreibung ist ein Teilsatz, der beschreibt, was die Ressource darstellt. Um weitere Details hinzuzufügen, verwenden Sie zusätzliche Sätze. In Ihrer .proto-Datei wird eine Ressourcenbeschreibung als Kommentar zum entsprechenden Nachrichtentyp hinzugefügt, wie im folgenden Beispiel:

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

Hier einige Beispiele zu Ressourcenbeschreibungen:

• Eine Aufgabe auf der To-do-Liste des Nutzers. Jede Aufgabe hat eine eindeutige Priorität.
• Ein Ereignis im Kalender des Nutzers.

Feld- und Parameterbeschreibungen

Eine Nominalphrase, die wie in den folgenden Beispielen ein Feld oder eine Parameterdefinition beschreibt:

• Die Anzahl der Themen in dieser Reihe.
• Die Genauigkeit von Breiten- und Längengradkoordinaten in Metern. Darf nicht negativ sein.
• Ein Flag, das angibt, ob für übermittelte Ressourcen in dieser Reihe Werte für URL-Anhänge zurückgegeben werden. Der Standardwert für series.insert ist true.
• Der Container für Abstimmungsinformationen. Ist nur beim Aufzeichnen von Abstimmungsinformationen vorhanden.
• Wird derzeit nicht verwendet oder wurde eingestellt.

Feld- und Parameterbeschreibungen sollten beschreiben, welche Werte gültig und ungültig sind. Entwickler geben ihr Bestes, um Dienste einzuführen, können aber den zugrundeliegenden Code nicht lesen, um unverständliche Informationen zu klären.

Bei Strings sollte die Beschreibung die Syntax und die zulässigen Zeichen sowie eine eventuell erforderliche Codierung beschreiben. Beispiel:

• 1–255 Zeichen im Satz [A-a0-9]
• Ein gültiger URL-Pfadstring, beginnend mit /, der RFC 2332-Konventionen entspricht. Darf maximal 500 Zeichen lang sein.

Die Beschreibung sollte jeden Standardwert oder jedes Verhalten angeben, kann aber möglicherweise die Beschreibung von Standardwerten, die effektiv null sind, weglassen.

Wenn der Feldwert erforderlich, nur für die Eingabe oder nur für die Ausgabe ist, sollte dies am Anfang der Feldbeschreibung angegeben werden. Standardmäßig sind alle Felder und Parameter optional. Beispiel:

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;
}

Hinweis: Feldbeschreibungen sollten nach Möglichkeit einen Beispielwert enthalten.

Methodenbeschreibung

Eine Methodenbeschreibung gibt in einem Satz an, wie sich die Methode auswirkt und für welche Ressourcen sie gilt. Sie beginnt normalerweise mit einem Verb im Präsens der dritten Person, im Englischen also einem Verb mit der Endung "s". Um weitere Details hinzuzufügen, verwenden Sie zusätzliche Sätze. Hier sind einige Beispiele:

• Listet Kalenderereignisse für den authentifizierten Nutzer auf.
• Aktualisiert ein Kalenderereignis mit den Daten der Anfrage.
• Löscht einen Standortdatensatz aus dem Standortverlauf des authentifizierten Nutzers.
• Erstellt oder aktualisiert mithilfe der in der Anfrage enthaltenen Daten einen Standortdatensatz im Standortverlauf des authentifizierten Nutzers. Wenn bereits eine Standortressource mit demselben Zeitstempelwert vorhanden ist, werden die vorhandenen Daten durch die bereitgestellten Daten überschrieben.

Checkliste für alle Beschreibungen

Stellen Sie sicher, dass jede Beschreibung kurz, aber vollständig ist und von Nutzern verstanden werden kann, die keine weiteren Informationen zur API haben. In den meisten Fällen ist mehr zu sagen, als nur das Offensichtliche zu wiederholen. In der Beschreibung der Methode series.insert sollte beispielsweise nicht einfach "Reihe einfügen" stehen. - Ihre Benennung sollte verständlich sein, die meisten Leser lesen Ihre Beschreibungen, weil sie mehr Informationen benötigen als die von ihnen selbst angegebenen Namen. Wenn Sie nicht sicher sind, was Sie in einer Beschreibung noch erwähnen könnten, versuchen Sie, alle der folgenden Fragen zu beantworten, sofern diese relevant sind:

• Was ist sie?
• Was passiert, wenn sie erfolgreich ist? Was passiert, wenn sie fehlschlägt? Wodurch kann sie fehlschlagen und wie?
• Ist sie idempotent?
• Welche Einheiten werden verwendet? (Beispiele: Meter, Grad, Pixel)
• Welche Wertebereiche werden akzeptiert? Sind die Start- und Endwerte ein- oder ausgeschlossen?
• Welche Nebenwirkungen können auftreten?
• Wie wird sie verwendet?
• Durch welche häufigen Fehler kann sie fehlschlagen?
• Ist sie immer präsent? (Beispiel: "Container für Abstimmungsinformationen. Nur beim Aufzeichnen von Abstimmungsinformationen vorhanden.")
• Gibt es eine Standardeinstellung?

Konventionen

In diesem Abschnitt werden einige Nutzungskonventionen für Textbeschreibungen und Dokumentationen aufgeführt. Verwenden Sie zum Beispiel "ID" (in Großbuchstaben) anstelle von "Id" oder "id", wenn es um Kennzeichnungen geht. Verwenden Sie "JSON" statt "Json" oder "json", wenn Sie dieses Datenformat angeben. Alle Feld-/Parameternamen in code font anzeigen. Geben Sie literale Stringwerte in code font und Anführungszeichen an.

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

Anforderungsstufen

Geben Sie Erwartungen oder Anforderungsstufen mit folgenden Begriffen an: muss, darf nicht, erforderlich, wird, wird nicht, soll, soll nicht, empfohlen, kann und optional.

Die Bedeutungen sind in RFC 2119 definiert. Sie können gegebenenfalls die Anweisung aus dem RFC-Abstrakt in der API-Dokumentation angeben.

Ermitteln Sie, welcher Begriff Ihren Anforderungen entspricht und Entwicklern gleichzeitig eine flexible Handhabung ermöglicht. Verwenden Sie keine absoluten Begriffen wie muss, wenn technisch gesehen auch andere Optionen in der API funktionieren.

Sprachstil

Ebenso wie bei unseren Namenskonventionen empfehlen wir auch beim Schreiben von Dokumentkommentaren, das Vokabular und den Stil einfach und konsistent zu halten. Kommentare sollten für Leser, deren Muttersprache nicht Englisch ist, verständlich sein. Vermeiden Sie daher Fachbegriffe, Slang, komplexe Metaphern, Verweise auf die Popkultur oder jegliche sonstigen Ausdrücke, die sich nur schwer übersetzen lassen. Verwenden Sie einen freundlichen, professionellen Stil und sprechen Sie die Entwickler direkt an. Halten Sie die Kommentare so knapp, aber verständlich wie möglich. Leser möchten in der Regel schnell ans Ziel gelangen und keine lange Dokumentation lesen.