不知道你是否浏览过 kube-apiserver 的 API 文档，官方地址在这：https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.21/
Kubernetes 的 API 遵循了 OpenAPI 规范，OpenAPI Spec 定义了一个标准的、语言无关的 RESTful API 接口规范，该规范使得人类和计算机都能在“不接触任何程序源代码和文档、不监控网络通信”的情况下理解一个服务的作用。由于采用了 OpenAPI 规范来定义 API，Kubernetes 就可以很方便的用文档生成工具来展示自己的 API，用代码生成工具来自动生成各种编程语言的服务器端和客户端的代码，用自动测试工具进行测试等等。这大概就是标准带来的红利吧！
那么，Kubernetes 是如何生成官网的 API 文档的呢？简单流程图大致如下：
总结起来，主要分为 3 个关键步骤：
- 1.使用 openapi-gen 工具（与 deepcopy-gen、defaulter-gen 类似，openapi-gen 同样基于 gengo 实现代码生成），通过注释信息生成包含 OpenAPI 定义的 go 模板代码。其中注释信息最关键的是
+k8s:openapi-gen=true这条注解，只要为外部类型添加包级别的该注解，openapi-gen 就会扫描该包下的所有类型，为其生成 OpenAPI 定义； - 2.kube-apiserver 引用生成的 OpenAPI 定义，注册到
/openapi/v2服务端点，客户端通过访问 apiserver 的 /openapi/v2 地址获取一个 swagger.json 文件，这个文件包含了 apiserver 的全部 OpenAPI 定义信息，kubernetes 项目下存在一个名为hack/update-openapi-spec.sh脚本，专门负责执行这个过程以更新api/openapi-spec/swagger.json文件； - 3.website 借助一个名叫 reference-docs 的工具，将 swagger.json 配合一些既定模版，一起转换为 HTML 格式页面，通过 hugo 渲染出来，就达到了官网 API 展示的效果了;
以上就是 kube-apiserver OpenAPI 文档的基本产生过程，关于具体的 openapi-gen 实现原理，我们下期再聊！