文档

本部分介绍了如何向 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 个字符。
  • 应尽可能提供示例值。
  • 如果字段值是必需仅限输入、仅限输出,则必须在字段说明开头记录这些值。默认情况下,所有字段和参数都是可选的。例如:
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;
}

方法说明

方法说明是一个指明方法效果及其操作资源的句子。它通常以第三人称的现在时态动词(即以“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,而不是阅读您的文档!