インライン API のドキュメント

このセクションでは、API にインラインドキュメントを追加するためのガイドラインを示します。ほとんどの API には、この設計ガイドの対象外となる概要、チュートリアル、上位レベルのリファレンスドキュメントも含まれます。API、リソース、メソッドの命名については、命名規則をご覧ください。

proto ファイルのコメント形式

通常のプロトコルバッファの // コメント形式を使用して、.proto ファイルにコメントを追加します。

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

サービス構成のコメント

.proto ファイルにドキュメントコメントを追加する代わりに、YAML サービス構成ファイルで API にインラインドキュメントを追加できます。両方のファイルに同じ要素が記述されている場合、このファイルのドキュメントが .proto のドキュメントよりも優先されます。

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

同じ .proto ファイルを使用する複数のサービスがあり、サービス固有のドキュメントを提供する必要がある場合は、この方法を使用してください。YAML ドキュメントルールでは、より詳細な overview を API の説明に追加することもできます。ただし、一般的にはドキュメントコメントを .proto に追加することをおすすめします。

.proto コメントと同様に、Markdown を使用して YAML ファイルのコメントに追加の書式を設定できます。

API の説明

API の説明は、API でできることを記述した能動態動詞で始まるフレーズです。.proto ファイルでは、次の例のように、API の説明が対応する service にコメントとして追加します。

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

API の説明の例をさらにいくつか示します。

Shares updates, photos, videos, and more with your friends around the world.
Accesses a cloud-hosted machine learning service that makes it easy to build smart apps that respond to streams of data.

リソースの説明

リソースの説明は、リソースが表すものを記述する部分文です。詳細を追加する必要がある場合は、追加の文を使用します。次の例のように、.proto ファイルでは、リソースの説明は対応するメッセージタイプにコメントとして追加されます。

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

リソースの説明の例を次に示します。

A task on the user's to-do list. Each task has a unique priority.
An event on the user's calendar.

フィールドとパラメータの説明

次の例に示すように、フィールドまたはパラメータの定義を記述する名詞句です。

The number of topics in this series.
The accuracy of the latitude and longitude coordinates, in meters. 非負でなければなりません。
Flag governing whether attachment URL values are returned for submission resources in this series. series.insert のデフォルト値は true です。
The container for voting information. Present only when voting information is recorded.
Not currently used or deprecated.

フィールドとパラメータの説明には、有効な値と無効な値を記述することが推奨されます。エンジニアは、サービスを中断するために最善を尽くしますが、基盤となるコードを読んで不明な情報を明らかにすることはできないことにご注意ください。

文字列の場合、説明には構文と許容される文字、および必要なエンコードを記述することが推奨されます。例:

セット内の 1～255 文字 [A-a0-9]。
/ で始まる、RFC 2332 の規則に従う有効な URL パス文字列。最大長は 500 文字です。

説明では、デフォルト値または動作を指定することが推奨されますが、事実上 null であるデフォルト値の説明は省略できます。

フィールド値が required、input only、output only の場合は、フィールドの説明の最初にドキュメント化することが推奨されます。デフォルトでは、すべてのフィールドとパラメータは省略可能です。例:

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

メソッドの説明

メソッドの説明は、メソッドがどのような効果を持ち、どのリソース上で動作するかを示す文です。通常、三人称の現在時制の動詞（つまり、英語では「s で終わる動詞」）で始まります。詳細を追加する必要がある場合は、追加の文を使用します。次に例を示します。

Lists calendar events for the authenticated user.
Updates a calendar event with the data included in the request.
Deletes a location record from the authenticated user's location history.
Creates or updates a location record in the authenticated user's location history using the data included in the request. If a location resource already exists with the same timestamp value, the data provided overwrites the existing data.

すべての説明のチェックリスト

各説明は簡潔で完全なもので、API に関する追加情報を持たないユーザーにも理解できるようにしてください。ほとんどの場合、明確に書き直すだけでは十分ではありません。たとえば、series.insert メソッドの説明は、単に「Inserts a series」とはしません。わかりやすい名前にする一方、ほとんどの読者は、名前自体が示すものよりも詳しい情報を求めています。説明で付け加える情報がわからない場合は、次の質問のうち、関連するすべてのものについて、回答を考えてみます。

これは何ですか？
成功するとどうなりますか？失敗するとどうなりますか？何がどのように失敗する原因になりますか？
べき等ですか？
単位は何ですか？（例: メートル、度、ピクセル）
どのような範囲の値が受け入れられますか？範囲は包含ですか排他ですか？
どのような副作用がありますか？
どのように使用しますか？
破損させる可能性がある一般的なエラーは何ですか？
常に存在しますか？（例: 「投票情報のコンテナ。投票情報が記録されている場合にのみ存在します」）
デフォルト設定がありますか？

規則

ここでは、テキスト記述とドキュメントの使用法の規則を示します。たとえば、識別子について説明するときは、「Id」や「id」ではなく、「ID」（すべて大文字）を使用します。データ形式を指すときは、「Json」や「json」ではなく、「JSON」を使用します。フィールド名とパラメータ名はすべて code font で表示します。リテラル文字列値は code font で引用符に入れます。

ID
JSON
RPC
REST
property_name または "string_literal"
true/false

要求レベル

期待や状態の要求レベルを設定するには、次の用語を使用します。must、must not、required、shall、shall not、should、should not、recommended、may、optional。

意味は RFC 2119 で定義されています。 API のドキュメントに RFC の抜粋の文を含めることができます。

デベロッパーに柔軟性を提供する一方で、どの用語が要件を満たすかを判断します。API で他の選択肢が技術的に機能する場合は、must のような絶対的な用語を使用しないでください。

言語スタイル

命名規則の場合と同様に、ドキュメントのコメントを記述するときは、単純で整合性のある語彙とスタイルを使用することをおすすめします。コメントは英語を母語としない読者が理解できる必要があるため、業界用語、スラング、複雑な暗喩、ポップカルチャーへの言及や、その他すべての翻訳困難なものは避けてください。コメントを読むデベロッパーに直接語りかける、わかりやすくプロフェッショナルなスタイルを使用し、できるだけ簡潔にします。ほとんどの読者の目的は、ドキュメントを読むことではなく、API を使用して何かをする方法を見つけることであることを忘れないようにします。

設計パターン

proto3 の使用