本文发布于一年多以前。较旧的文章可能包含过时的内容。请检查页面中的信息自发布以来是否已变得不正确。

GSoD 2020：改进 API 参考体验

作者：Philippe Martin |

编者注：自从我加入 Kubernetes 文档团队三年半以来，我的目标一直是改进 API 参考。Philippe 出色地完成了这项任务。但不仅仅是一个更好的 API 参考，Philippe 在这个项目中体现了 Kubernetes 社区的精华：通过协作追求卓越，以及一个使社区本身变得更好的过程。感谢 Google Season of Docs，使 Philippe 的工作成为可能。 —Zach Corleissen

引言

Google Season of Docs 项目将开源组织和技术作家聚集在一起，紧密合作完成特定的文档项目。

我被 CNCF 选中从事 Kubernetes 文档工作，特别是使 API 参考文档更易于访问。

我是一名对文档系统非常感兴趣的软件开发人员。在 90 年代后期，我开始将 Linux-HOWTO 文档翻译成法语。从一件事到另一件事，我了解了文档系统。最终，我编写了一个 Linux-HOWTO，以帮助文档编写者学习当时用于编写文档的语言 LinuxDoc/SGML。

此后不久，Linux 文档采用了 DocBook 语言。我帮助一些作者以这种格式重写他们的文档；例如，《高级 Bash 脚本指南》。我还参与了 GNU makeinfo 程序，添加了 DocBook 输出，从而可以将 GNU Info 文档转换为 Docbook 格式。

背景

Kubernetes 网站使用 Hugo 从 website 存储库中以 Markdown 格式编写的文档构建，使用 Docsy Hugo 主题。

现有的 API 参考文档是一个从 Kubernetes OpenAPI 规范生成的大型 HTML 文件。

就我而言，我一直想通过以下方式使 API 参考更易于访问：

  • 为每个 Kubernetes 资源构建单独且独立的页面
  • 使格式适应移动阅读
  • 重用网站的资源和主题来构建、集成和显示参考页面
  • 允许搜索引擎引用页面的内容

大约一年前，我开始研究构建当前唯一 HTML 页面的生成器，以添加 DocBook 输出，因此可以首先以 DocBook 格式生成 API 参考，然后在 PDF 或 DocBook 处理器支持的其他格式中生成。第一个结果是一些 API 参考的电子书文件和一本自动编辑的纸质书。

我后来决定向此生成器添加另一个输出，以生成 Markdown 文件并创建一个 包含 API 参考的网站。

当 CNCF 提出一个 Google Season of Docs 项目来处理 API 参考时，我申请了，并且配对成功。

项目

swagger-ui

CNCF 成员提出此项目的第一个想法是测试 swagger-ui 工具，尝试使用此标准工具记录 Kubernetes API 参考。

由于 Kubernetes API 比许多其他 API 大得多，因此有必要编写一个工具来按 API 组拆分完整的 API 参考，并在文档网站中插入多个 swagger-ui 组件，每个 API 组一个。

通常，开发人员通过使用特定的 HTTP 动词调用端点、使用特定参数并等待响应来使用 API。swagger-ui 接口是为此用法而构建的：该接口显示端点列表及其关联的动词，以及每个端点的参数和响应格式。

Kubernetes API 大多数情况下以不同的方式使用：用户创建包含 YAML 格式的资源定义的清单文件，并使用 kubectl CLI 将这些清单应用到集群。在这种情况下，最重要的信息是用于参数和响应的结构（Kubernetes 资源）的描述。

由于这种特殊性，我们意识到很难使 swagger-ui 接口适应 Kubernetes API 的用户，并且这个方向已经被放弃。

Markdown 页面

该项目的第二阶段是调整我为创建 k8sref.io 网站所做的工作，将其包含在官方文档网站中。

主要更改是：

  • 使用 go-templates 来表示输出页面，以便非开发人员可以调整生成的页面，而无需编辑生成器代码
  • 创建一个新的自定义 shortcode，以便轻松地从网站内部创建到 API 参考特定页面的链接
  • 改进 API 参考各部分之间的导航
  • 将生成器的代码添加到包含不同参考生成器的 Kubernetes GitHub 存储库中

所有讨论和工作都可以在网站 pull request #23294 中找到。

将生成器代码添加到 Kubernetes 项目发生在 kubernetes-sigs/reference-docs#179。

以下是要包含在官方文档网站中的新 API 参考的功能：

  • 资源按类别分类，分为工作负载、服务、配置和存储、身份验证、授权、策略、扩展、集群。此结构可以使用简单的 toc.yaml 文件进行配置
  • 每个页面在第一级显示关联的资源；例如：Pod、PodSpec、PodStatus、PodList
  • 大多数资源页面内联相关的定义；例外情况是这些定义对多个资源通用，或者过于复杂而无法内联显示。使用旧的方法，您必须点击一个超链接才能读取每个额外的细节。
  • 一些广泛使用的定义，例如 ObjectMeta，记录在一个特定的页面中
  • 必需字段会被指示，并放在首位
  • 可以使用 fields.yaml 文件对资源的字段进行分类和排序
  • map 字段会被指示。例如，Pod 的 .spec.nodeSelector 是 map[string]string，而不是 object，使用 x-kubernetes-list-type 的值
  • 修补策略会被指示
  • apiVersion 和 kind 显示值，而不是 string 类型
  • 在参考页面的顶部，该页面显示从 Go 程序中使用这些资源所必需的 Go 导入。

目前，该工作因等待 1.20 版本发布而暂停。当发布完成并且工作集成后，API 参考将在 https://kubernetes.top/docs/reference/ 上提供。

未来工作

有一些需要改进的地方，特别是：

  • 某些 Kubernetes 资源是深层嵌套的。内联这些资源的定义使它们难以理解。
  • 创建的 shortcode 使用页面的 URL 来引用资源页面。如果文档编写者可以通过其组和名称来引用资源，则会更容易。

致谢

我要感谢我的导师 Zach Corleissen 和首席撰稿人 Karen Bradshaw、Celeste Horgan、Tim Bannister 和 Qiming Teng，他们在整个赛季中都指导了我。他们都非常鼓励我，并给了我很多很好的建议。