• 文档
    • 注释格式
    • 服务配置中的注释
    • API 描述
    • 资源描述
    • 字段和参数描述
    • 方法描述
    • 描述信息备忘录
    • 约定
      • 语言风格

    文档

    本章节为 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,而不是阅读你的文档!