本页面介绍了如何更新 Kubernetes API 参考文档。
Kubernetes API 参考文档是通过 Kubernetes OpenAPI 规范，并使用 kubernetes-sigs/reference-docs 生成代码构建的。
如果您在生成的文档中发现错误，需要在上游进行修复。
如果您只需要根据 OpenAPI 规范重新生成参考文档，请继续阅读本页面。
您需要一台运行 Linux 或 macOS 的机器。
您需要安装以下工具
您的 PATH 环境变量必须包含所需的构建工具，例如 Go 二进制文件和 python。
您需要知道如何创建 GitHub 仓库的拉取请求。这涉及创建您自己的仓库分叉。有关更多信息，请参阅 从本地克隆工作。
创建本地工作区并设置您的 GOPATH
mkdir -p $HOME/<workspace>
export GOPATH=$HOME/<workspace>
克隆以下仓库的本地副本
git clone github.com/kubernetes-sigs/reference-docs
进入 reference-docs 仓库的 gen-apidocs 目录，并安装所需的 Go 包
go get -u github.com/go-openapi/loads
go get -u github.com/go-openapi/spec
如果您还没有 kubernetes/website 仓库，请现在获取它
git clone https://github.com/<your-username>/website
获取 kubernetes/kubernetes 仓库的克隆
git clone https://github.com/kubernetes/kubernetes
您克隆的 kubernetes/kubernetes 仓库的基本目录是 <your-path-to>/kubernetes/kubernetes。后续步骤将该基本目录称为 <k8s-base>。
您克隆的 kubernetes/website 仓库的基本目录是 <your-path-to>/website。后续步骤将该基本目录称为 <web-base>。
您克隆的 kubernetes-sigs/reference-docs 仓库的基本目录是 <your-path-to>/reference-docs。后续步骤将该基本目录称为 <rdocs-base>。
本节展示了如何生成已发布的 Kubernetes API 参考文档。
K8S_ROOT 设置为 <k8s-base>。K8S_WEBROOT 设置为 <web-base>。K8S_RELEASE 设置为您想要构建的文档版本。例如，如果您想构建 Kubernetes 1.17.0 的文档，请将 K8S_RELEASE 设置为 1.17.0。例如
export K8S_WEBROOT=<your-path-to>/website
export K8S_ROOT=<your-path-to>/kubernetes
export K8S_RELEASE=1.17.0
updateapispec 构建目标会创建版本化的构建目录。目录创建后，将从 <k8s-base> 仓库获取 Open API 规范。这些步骤确保配置文件版本与 Kubernetes Open API 规范匹配发布版本。版本化目录的命名遵循 v<major>_<minor> 的模式。
在 <rdocs-base> 目录下，运行以下构建目标
cd <rdocs-base>
make updateapispec
copyapi 目标会构建 API 参考并将生成的文件复制到 <web-base> 中的目录。在 <rdocs-base> 目录下运行以下命令
cd <rdocs-base>
make copyapi
验证这两个文件是否已生成
[ -e "<rdocs-base>/gen-apidocs/build/index.html" ] && echo "index.html built" || echo "no index.html"
[ -e "<rdocs-base>/gen-apidocs/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"
进入本地 <web-base> 的基本目录，查看哪些文件已被修改
cd <web-base>
git status
输出类似于
static/docs/reference/generated/kubernetes-api/v1.36/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.36/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.36/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.36/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.36/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.36/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.36/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.36/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.36/fonts/fontawesome-webfont.woff2
static/docs/reference/generated/kubernetes-api/v1.36/index.html
static/docs/reference/generated/kubernetes-api/v1.36/js/jquery.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.36/js/navData.js
static/docs/reference/generated/kubernetes-api/v1.36/js/scroll.js
生成的 API 参考文件（HTML 版本）会被复制到 <web-base>/static/docs/reference/generated/kubernetes-api/v1.36/。该目录包含独立的 HTML API 文档。
<web-base>/content/en/docs/reference/kubernetes-api/ 的 API 参考 Markdown 版本是使用 gen-resourcesdocs 生成器单独生成的。发布 API 参考的本地版本。验证本地预览。
cd <web-base>
git submodule update --init --recursive --depth 1 # if not already done
make container-serve
在 <web-base> 中，运行 git add 和 git commit 来提交更改。
以拉取请求 (Pull Request) 的形式提交您的更改至 kubernetes/website 仓库。监控您的拉取请求，并根据需要回应评审者的评论。持续监控您的拉取请求直到它被合并。