文档

本章节为 API 添加文档提供了指南。 大多数 API 将提供概述、教程和更高级别的参考文档，这些内容本设计指南并不涉及。 有关 API 命名、资源命名和方法命名的信息，请参阅命名约定。

注释格式

在 .proto 文件中可以使用 Protocol Buffers 通常的注释格式(\\)来添加注释

  1. // Creates a shelf in the library, and returns the new Shelf.
  2. rpc CreateShelf(CreateShelfRequest) returns (Shelf) {
  3.   option (google.api.http) = { post: "/v1/shelves" body: "shelf" };
  4. }

服务配置中的注释

另一种向 .proto 文件添加注释的方法是，可以在其 YAML 服务配置文件中为 API 添加内联文档。 如果两个文件中都记录了相同的元素，则 YAML 中的文档将优先于 .proto 中的文档。

  1. documentation:
  2.   summary: Gets and lists social activities
  3.   overview: A simple example service that lets you get and list possible social activities
  4.   rules:
  5.   - selector: google.social.Social.GetActivity
  6.     description: Gets a social activity. If the activity does not exist, returns Code.NOT_FOUND.

如果有多个服务定义在同一个 .proto 文件中，并且希望为每个服务提供文档，则可能需要使用此方法。在 YAML 文还可以为 API 添加更详细的概述。但是一般情况下，推荐在 .proto 文件中添加文档注释。

与 .proto 注释一样，可以使用 Markdown 为 YAML 中的注释提供更多排版格式。

API 描述

API 描述是以行为动词开头的短语，描述了该 API 可以执行什么操作。在 .proto 文件中，API 描述作为注释添加到相应的服务(service)上，例如：

  1. // Manages books and shelves in a simple digital library.
  2. service LibraryService {
  3. ...
  4. }

下面是一些 API 描述的示例：

  • 分享你的动态、照片、视频给其他朋友。
  • 访问云托管的机器学习服务，可以轻松构建响应数据流的智能应用程序。

资源描述

资源描述是描述资源代表了什么的句子。如果需要添加更多详细信息，使用添加其他句子。在 .proto 文件中，资源描述作为注释添加到对应的消息类型上，如下：

  1. // A book resource in the Library API.
  2. message Book {
  3.   ...
  4. }

下面是一些资源描述的示例：

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

字段和参数描述

一个描述字段或参数定义的名词短语，例如：

  • 话题数量。
  • 经纬度坐标的精度（以米为单位），必须为非负数。
  • 标记是否为提交资源返回附件地址，series.insert 的默认值为 true。
  • 用于投票信息的容器，仅当记录投票信息时才存在。
  • 目前未使用或已弃用。

字段和参数描述

  • 必须清楚地描述边界（也就是说，明确什么是有效的什么是无效的。请记住，工程师不会阅读底下的代码来明确任何不清楚的信息。）
  • 必须指定默认值或默认行为。换句话说，如果没有提供任何值服务器将会是什么行为。
  • 如果是字符串（如名称或路径），请描述其语法规则并列出允许的字符以及所需的编码。例如：
    • 集合 [A-a0-9] 中1～255个字符
    • 以 / 开头的有效 URL 路径字符串，必须遵循 RFC 2332 约定。最大允许长度为500个字符
  • 尽可能提供示例值。
  • 如果字段值是必需的、或仅用于输入、或仅用于输出，那么必须在字段描述的开始处注明。默认情况下，所有字段和参数都是可选的。例如：
  1. proto message Table {
  2.     // Required. The resource name of the table.
  3.     string name = 1;
  4.     // Input only. Whether to dry run the table creation.
  5.     bool dyrun = 2;
  6.     // Output only. The timestamp when the table was created. Assigned by
  7.     // the server.
  8.     Timestamp create_time = 3;
  9.     // The display name of the table.
  10.     string display_name = 4;
  11. }

方法描述

方法描述是一个句子，指出该方法具有什么效果以及操作的资源。它通常以第三人称现在时态动词（即以 s 结尾的动词）开始。如果需要添加详细信息，可以使用更多的句子。例如：

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

描述信息备忘录

确保每个描述都是简短但完整的，并且能够让用户在没有 API 其他信息的情况下所理解。实际上，还有更多需要注意的事项。例如，方法 series.insert 的描述不应该只是说“插入一个系列”。尽管你在命名时应该易于理解，但读者之所以阅读你的描述，是因为他们需要获取更多的信息。如果您不确定需要在描述中表述什么，可以参考下面这些问题：

  • 它是什么？
  • 如果（请求）成功它会做什么？如果失败它会做什么？什么可能导致失败？
  • 它是幂等的吗？
  • 单位是什么？ （例如：米，度，像素。）
  • 它接受什么范围的值？范围是包含还是排他？
  • 有什么副作用吗？
  • 你该如何使用它？
  • 可能破坏它的常见错误有哪些？
  • 它总是存在吗？ （例如：“用于投票信息的容器，仅在记录投票信息时存在”。）
  • 它有默认设置吗？

约定

本节列出了文本描述和文档的一些使用约定。例如，在谈论标识符时，使用 “ID”（全大写），而不是 “Id” 或 “id”。在指代 JSON 数据格式时，请使用 “JSON” 而不是 “Json” 或 “json”。使用代码字体来表示所有字段和参数名称。字符串字面值以代码字体表示并放入引号中。

  • ID
  • JSON
  • RPC
  • REST
  • property_name 或 “string_literal”
  • true/false

语言风格

正如上一章节的命名约定，我们建议在编写文档注释时使用简单，一致的词汇。 注释应该易于母语非英语的读者理解，所以避免行话、俚语、复杂的隐喻、引用流行文化，或任何其他不容易翻译的内容。阅读注释时好似以友好、专业的风格直接与开发人员交流。请谨记，读者是为了了解如何使用 API，而不是阅读你的文档！