内嵌 API 文档

本部分介绍了如何向 API 添加内嵌文档。大多数 API 还拥有概览、教程和简要参考文档，这些内容本设计指南并不涉及。如需了解 API、资源和方法命名，请参阅命名惯例。

proto 文件中的注释格式

使用常用的 Protocol Buffers // 注释格式向 .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 添加内嵌文档。如果两个文件中都记录了相同的元素，则 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 文档规则还允许您向 API 说明添加更详细的 overview。但一般首选向 .proto 文件添加文档注释。 与向 .proto 添加注释一样，您可以使用 Markdown 在 YAML 文件注释中提供其他格式设置。

API 说明

API 说明是说明 API 功能的短语（以行为动词开头）。在您的 .proto 文件中，API 说明作为注释添加到相应的 service 中，如以下示例所示：

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

以下是一些 API 说明示例：

• 与世界各地的朋友分享最新动态、照片、视频等。
• 访问云托管的机器学习服务，轻松构建响应数据流的智能应用。

资源说明

资源说明是描述资源表示的内容的句子。如果您需要添加更多细节，请使用更多句子。在您的 .proto 文件中，API 说明作为注释添加到相应的消息类型中，如以下示例所示：

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

以下是一些资源说明示例：

• 用户待办事项列表中的一项任务。每项任务具有唯一的优先级。
• 用户日历上的一个事件。

字段和参数说明

描述字段或参数定义的名词短语，如以下示例所示：

• 本系列的主题数量。
• 经纬度坐标的精度，以米为单位。 必须是非负数。
• 标记是否为本系列的提交资源返回附件网址值。series.insert 的默认值为 true。
• 投票信息的容器。仅在记录投票信息时出现。
• 目前未使用或已弃用。

字段和参数说明应该描述哪些值有效和无效。请记住，工程师们会通过一切可能的途径导致服务失败，并且他们无法读取底层代码来澄清任何不清楚的信息。 对于字符串，说明应该描述语法和允许的字符以及任何所需的编码。例如：

• 集合 [A-a0-9] 中的 1-255 个字符
• 遵循 RFC 2332 惯例且以 / 开头的有效网址路径字符串。长度上限为 500 个字符。

说明应该指定任何默认值或行为，但可以省略描述实际为 null 的默认值。 如果字段值是必需、仅限输入、仅限输出，则應該在字段说明开头记录这些值。默认情况下，所有字段和参数都是可选的。例如：

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”结尾的动词）开头。如果需要添加详细信息，请使用更多句子。示例如下：

• 列出已通过身份验证的用户的日历事件。
• 使用请求中包含的数据来更新日历事件。
• 从已通过身份验证的用户的位置历史记录中删除一个位置记录。
• 在已通过身份验证的用户的位置历史记录中，使用请求中包含的数据创建或更新一个位置记录。如果已存在具有相同时间戳值的位置资源，则所提供的数据会覆盖现有数据。

所有说明的核对清单

确保每个说明都是简短而完整的，能够让用户在没有其他关于该 API 的信息的情况下所理解。在大多数情况下，都有更多需要说明的内容，而不仅仅是重复显而易见的信息。例如，series.insert 方法的说明不应该只是说“插入一个序列”。虽然您的命名应该包含信息，但大多数读者还是会阅读说明，因为他们需要名称之外的更多信息。如果您不确定需要在说明中包括哪些其他内容，请尝试回答以下所有相关问题：

• 它是什么？
• 如果成功了它会执行什么操作？如果失败了它会执行什么操作？什么可能导致它失败及如何导致它失败？
• 它具有幂等性吗？
• 它的单位是什么？（例如：米、度、像素。）
• 它接受什么范围的值？此范围是否包含边界值？
• 它有什么副作用？
• 应该如何使用它？
• 可能会导致它失败的常见错误有哪些？
• 它总是存在吗？（例如：“用于投票信息的容器。仅在记录投票信息时存在。”）
• 它有默认设置吗？

惯例

本部分列出了文本说明和文档的一些使用惯例。例如，在说明标识符时，请使用“ID”（全部大写），而不是“Id”或“id”。在引用该数据格式时，请使用“JSON”而不是“Json”或“json”。以 code font 显示所有字段/参数名称。将文字字符串值以 code font 表示，并将其放入引号中。

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

要求级别

要设置预期或陈述要求级别，请使用以下术语：必须、不得、必需、应、不应、应该、不应该、建议、可以和可选。 如需了解这些术语的含义，请参阅 RFC 2119 中的定义。 建议您在 API 文档中包含 RFC 摘要中的语句。 确定哪些术语既符合您的要求，又能为开发者提供灵活性。如果从技术上来说，您的 API 还支持其他选项，则请勿使用绝对术语（如“必须”）。

语言风格

如命名惯例中所述，我们建议在编写文档注释时使用简单、一致的词汇和风格。注释应该易于母语非英语的读者理解，所以应避免行话、俚语、复杂的隐喻、引用流行文化，或包含任何其他不容易翻译的内容。使用友好、专业的风格直接与阅读注释的开发者交流，并尽可能简明扼要。请记住，大多数读者的目的是了解如何使用 API，而不是阅读您的文档！