Google API 設計指南－文檔

翻譯自 API Design Guide - Documentation

這一章是爲 API 添加內部文檔的指南。大部分 API 有概述、教程和更高級別的參考文檔（此指南不討論）。API 名、資源名和方法名的信息請查看命名約定。

註釋格式

在 .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 文件中添加註釋的替代方法，你能夠在 API 的 YAML 服務配置文件中添加註釋。若是兩個文件中都記錄了相同的元素，則該文件中的文檔將優先於 .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 註釋同樣，能夠在 YAML 文件的註釋中使用 Markdown 來提供其餘格式。

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. Must be non-negative.

• Flag governing whether attachment URL values are returned for submission resources in this series. The default value for series.insert is true.

• The container for voting information. Present only when voting information is recorded.

• Not currently used or deprecated.

字段和參數描述:

• 必須清楚地描述邊界條件（描述哪些值有效哪些值無效。API 用戶會盡最大的可能來誤用服務，並且不能閱讀底層代碼來弄清楚）

• 必須指定默認值和默認行爲

• 當是字符串時，要描述語法、容許的字符和須要的編碼格式，例如

  • 1-255 characters in the set [A-a0-9]

  • A valid URL path string starting with / that follows the RFC 2332 conventions. Max length is 500 characters.

• 若是能夠的話，提供示例

• 當字段 必須、僅輸入、僅輸出 時，必須在字段描述的開始進行說明。默認狀況下全部字段和參數都是可選的。例如：

message Table {
  // Required. The resource name of the table.
  string name = 1;
  // Input only. Whether to dry run the table creation.
  bool dryrun = 2;
  // Output only. The timestamp when the table was created. Assigned by
  // the server.
  Timestamp create_time = 3;
  // The display name of the table.
  string display_name = 4;
}

方法描述

方法描述用來講明方法的做用和操做的資源。一般以第三人稱的如今時動詞開始。示例：

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

注意事項

確保描述簡潔完整而且容易被理解。不能僅作重述，例如 series.insert 方法的描述不能簡單地寫成 "Inserts a series"。命名應該包含豐富的信息，大多數讀者會閱讀描述，由於他們須要比名字自己更多的信息。若是不知道在描述中要寫什麼，試着回答下面的問題：

• 它是什麼

• 成功或失敗後會致使什麼。什麼會致使失敗。

• 是冪等的嗎

• 單位是什麼（例如：米、度、像素）

• 接收參數的範圍

• 反作用是什麼

• 如何使用

• 常見錯誤是什麼

• 是否老是存在（例如："Container for voting information. Present only when voting information is recorded."）

• 是否有默認值

慣例

本節列出了文本描述和文檔的一些使用慣例。使用 ID 表示標識符（而不使用 Id 或 id）。使用 JSON 表示數據格式（而不使用 Json 或 json）。全部字段/參數使用 code font 的格式，字符串要用引號括起來。

• ID

• JSON

• RPC

• REST

• property_name 或 "string_literal"

• true / false

語言風格

和命名約定同樣，在寫註釋時推薦使用簡潔一致的詞語和風格，讓母語非英語的讀者容易理解。所以要避免行話、俚語、複雜的隱喻、流行文化或其餘不容易理解的內容。使用友好專業的風格直接與讀者「交談」，並儘量保持註釋的簡潔。請記住，大部分讀者只想知道如何使用 API，而不是閱讀你的文檔！

查看其餘章節