文档

优质

小牛编辑

129浏览

2023-12-01

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

注释格式

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

// 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 添加更详细的概述。但是一般情况下，推荐在 .proto 文件中添加文档注释。

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

API 描述

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

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

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

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

资源描述

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

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

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

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

字段和参数描述

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

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

字段和参数描述

必须清楚地描述边界（也就是说，明确什么是有效的什么是无效的。请记住，工程师不会阅读底下的代码来明确任何不清楚的信息。）
必须指定默认值或默认行为。换句话说，如果没有提供任何值服务器将会是什么行为。
如果是字符串（如名称或路径），请描述其语法规则并列出允许的字符以及所需的编码。例如：
- 集合 [A-a0-9] 中1～255个字符
- 以 / 开头的有效 URL 路径字符串，必须遵循 RFC 2332 约定。最大允许长度为500个字符
尽可能提供示例值。
如果字段值是必需的、或仅用于输入、或仅用于输出，那么必须在字段描述的开始处注明。默认情况下，所有字段和参数都是可选的。例如：

proto message Table {
    // Required. The resource name of the table.
    string name = 1;
    // Input only. Whether to dry run the table creation.
    bool dyrun = 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” 或 “json”。使用代码字体来表示所有字段和参数名称。字符串字面值以代码字体表示并放入引号中。

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

语言风格

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