website/content/zh/docs/contribute/generate-ref-docs/kubernetes-api.md

title, content_template

title	content_template
为 Kubernetes API 生成参考文档	templates/task

{{% capture overview %}}

本页面展示了如何为 Kubernetes API 更新自动生成的参考文档。

{{% /capture %}}

{{% capture prerequisites %}}

你需要安装以下软件：

• Git
• 1.9 或更高版本的 Golang
• Docker
• etcd

在环境变量中设置 $GOPATH，并且 etcd 的路径必须配置在 $PATH 环境变量中。

你需要知道如何在一个 GitHub 项目仓库中创建一个 PR。一般来说，这涉及到创建仓库的一个分支。想了解更多信息，请参见创建一个文档 PR 和 GitHub 标准 Fork&PR 工作流。

{{% /capture %}}

{{% capture steps %}}

概述

更新 Kubernetes API 参考文档有两个步骤：

1. 从 kubernetes 源码生成 OpenAPI 规范。本步骤的工具在 kubernetes/kubernetes/hack。

1. 从 OpenAPI 规范生成 HTML 文件。本步骤的工具在 kubernetes-incubator/reference-docs。

下载三个仓库

If you don't already have the kubernetes/kubernetes repository, get it now:

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/kubernetes

确定 kubernetes/kubernetes 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 $GOPATH/src/github.com/kubernetes/kubernetes。下文将该目录称为 <k8s-base>。

如果你还没有下载过 kubernetes/website 仓库，现在下载：

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/website

确定 kubernetes/website 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 $GOPATH/src/github.com/kubernetes/website。下文将该目录称为 <web-base>。

如果你还没有下载过 kubernetes-incubator/reference-docs 仓库，现在下载：

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes-incubator/reference-docs

确定 kubernetes-incubator/reference-docs 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 $GOPATH/src/github.com/kubernetes-incubator/reference-docs。下文将该目录称为 <rdocs-base>。

编辑 Kubernetes 源码

Kubernetes API 参考文档是基于 OpenAPI 规范自动生成的，而该规范是从 Kubernetes 源码生成的。如果想要修改参考文档，可以从修改 Kubernetes 源码中的一个或多个注释开始。

修改源码中的注释

{{< note >}}

以下步骤是一个示例，而不是通用步骤。在你操作过程中，细节会有所不同。 {{< /note >}}

下面是在 Kubernetes 源码中编辑注释的示例。

进入 kubernetes/kubernetes 仓库的本地目录，检出 master 分支，并确保它是最新的：

cd <k8s-base>
git checkout master
git pull https://github.com/kubernetes/kubernetes master

假设 master 分支中的这个源文件有一个拼写错误 "atmost"：

kubernetes/kubernetes/staging/src/k8s.io/api/apps/v1/types.go

在本地环境中，打开 types.go 文件，然后将 "atmost" 修改为 "at most"。

确认文件已修改：

git status

输出展示了在 master 分支上，types.go 文件已被修改：

On branch master
...
    modified:   staging/src/k8s.io/api/apps/v1/types.go

提交已编辑的文件

运行 git add 和 git commit 提交到目前为止所做的修改。在下一步中，你将进行第二次提交。将修改拆分为两个提交是很重要的。

生成 OpenAPI 规范和相关文件

进入 <k8s-base> 目录运行以下脚本：

hack/update-generated-swagger-docs.sh
hack/update-swagger-spec.sh
hack/update-openapi-spec.sh
hack/update-generated-protobuf.sh
hack/update-api-reference-docs.sh

运行 git status 查看生成的文件。

On branch master
...
    modified:   api/openapi-spec/swagger.json
    modified:   api/swagger-spec/apps_v1.json
    modified:   docs/api-reference/apps/v1/definitions.html
    modified:   staging/src/k8s.io/api/apps/v1/generated.proto
    modified:   staging/src/k8s.io/api/apps/v1/types.go
    modified:   staging/src/k8s.io/api/apps/v1/types_swagger_doc_generated.go

检查 api/openapi-spec/swagger.json 的内容确认拼写错误是否被修复。例如，你可以运行 git diff -a api/openapi-spec/swagger.json。这个步骤很重要，因为 swagger.json 是文档生成过程的第二个步骤的输入。

运行 git add 和 git commit 提交修改。现在你有两个提交：一个是已编辑的 types.go 文件，另一个是已生成的 OpenAPI 规范和相关文件。把这两个提交分开。也就是说，不要将它们合并提交。

将你的修改以 pull request 提交到 kubernetes/kubernetes 仓库的 master 分支。跟踪你的 PR，并根据需要回应评审人的评论。继续跟踪你的 PR，直到它被合入。

PR 57758 是一个对 Kubernetes 源码中的拼写错误进行修复的 PR 示例。

{{< note >}}

定位要修改的具体源文件可能很困难。在前面的示例中，正确的源文件位于 kubernetes/kubernetes 仓库的 staging 目录下。但在你的情况下，staging 目录可能不是查找正确源的位置。有关指导，请查看 kubernetes/kubernetes 仓库的 README 文件和相关仓库 kubernetes/apiserver。 {{< /note >}}

以 cherry-pick 方式将你的提交合入已发布分支

在上文中，你在 master 分支中编辑了一个文件，然后运行脚本来生成 OpenAPI 规范和相关文件。然后你在一个 PR 中向 kubernetes/kubernetes 仓库的 master 分支提交了修改。现在假设你想要将你的修改合入到一个发布分支中。例如，假设 master 分支用于开发 Kubernetes 1.10 版本，而你希望将你的修改合入到 release-1.9 分支中。

回想一下 PR 中有两个提交：一个用于编辑 types.go，另一个用于脚本生成的文件。下一步是对你在 release-1.9 分支的第一次提交提议一个 cherry-pick 合入。其目的是挑出对 types.go 的编辑的那次提交，而不是对运行脚本结果的提交。有关说明，请参见提议一个 cherry-pick 合入。

{{< note >}}

提议一个 cherry-pick 合入，需要你有在 PR 中设置标签和里程碑的权限。如果你没有，你需要与有权限为你设置标签和里程碑的人合作完成。 {{< /note >}}

当你有一个对 release-1.9 分支进行 cherry-pick 合入的 PR 时，下一步是在 release-1.9 分支的本地环境中运行这些脚本。

hack/update-generated-swagger-docs.sh
hack/update-swagger-spec.sh
hack/update-openapi-spec.sh
hack/update-generated-protobuf.sh
hack/update-api-reference-docs.sh

现在向 cherry pick 的 PR 添加一个提交，该 PR 包含最近生成的 OpenAPI 规范和相关文件。跟踪你的 PR，直到它合入到 release-1.9 分支中。

此时，master 和 release-1.9 分支都更新了 types.go 文件和一组生成的文件，这些反映了你对 types.go 做的修改。注意，在 release-1.9 分支中生成的 OpenAPI 规范和其他文件不一定与在 master 分支中生成的文件相同。在 release-1.9 分支中生成的文件只包含 Kubernetes 1.9 版本的 API 元素。master 分支中生成的文件可能包含正在 1.10 版本中开发的 API 元素，而这些元素却不在 1.9 版本中。

生成已发布的参考文档

前一章节展示了如何编辑源文件，然后生成几个文件，包括 kubernetes/kubernetes 仓库中的 api/openapi-spec/swagger.json。

本章节介绍如何生成[已发布的 Kubernetes API 参考文档](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/)，该文档由 kubernetes-incubator/reference-docs 中的工具生成。这些工具以 api/openapi-spec/swagger.json 文件作为输入。

在 kubernetes-incubator/reference-docs 仓库中编辑 Makefile 文件

进入 <rdocs-base> 目录, 打开 Makefile 进行编辑：

将 K8SROOT 设置为 kubernetes/kubernetes 仓库的本地主目录。将 WEBROOT 设置为 kubernetes/website 仓库的本地主目录。将 MINOR_VERSION 设置为要构建的文档的副版本号。例如，如果要为 Kubernetes 1.9 版本构建文档，请将 MINOR_VERSION 设置为 9。保存并关闭 Makefile。

复制 OpenAPI 规范

文档生成代码需要 Kubernetes API 的 OpenAPI 规范的本地副本。进入 <k8s-base> 目录，检出有你想要使用的 OpenAPI 规范的分支。例如，如果要为 Kubernetes 1.9 版本生成文档，请检出 release-1.9 分支。

返回 <rdocs-base> 目录。输入以下命令将 OpenAPI 规范从 kubernetes/kubernetes 仓库复制到本地目录：

make updateapispec

输出显示文件已被复制：

cp ~/src/github.com/kubernetes/kubernetes/api/openapi-spec/swagger.json gen-apidocs/generators/openapi-spec/swagger.json

制作 brodocs 镜像

文档生成代码需要 pwittrock/brodocs Docker 镜像。

该命令用于创建 pwittrock/brodocs Docker 镜像。它还尝试将镜像推送到 DockerHub，但是如果该步骤失败也没关系。只要镜像在本地，就可以成功生成代码。

make brodocs

确认 brodocs 镜像是否存在：

docker images

输出显示 pwittrock/brodocs 是可用镜像之一：

REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
pwittrock/brodocs   latest              999d34a50d56        5 weeks ago         714MB

运行文档生成代码

构建并运行文档生成代码。你可能需要以 root 用户运行命令：

cd <rdocs-base>
make api

找到生成的文件

这两个文件是成功构建的产物。验证它们是否存在：

• <rdocs-base>/gen-apidocs/generators/build/index.html
• <rdocs-base>/gen-apidocs/generators/build/navData.js

将生成的文档复制到 kubernetes/website 仓库

前面的章节展示了如何编辑 Kubernetes 源文件，生成 OpenAPI 规范，然后生成用于发布的参考文档。

本章节介绍如何将生成的文档复制到 kubernetes/website 仓库。kubernetes/website 仓库中的文件发布在 kubernetes.io 网站上。特别是，生成的 index.html 文件发布在[这里](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/)。

输入以下命令将生成的文件复制到 kubernetes/website 仓库的本地目录：

make copyapi

进入 kubernetes/kubernetes 仓库的本地主目录，查看哪些文件已被修改：

cd <web-base>
git status

输出显示修改后的文件：

On branch master
...
   modified:   docs/reference/generated/kubernetes-api/v1.9/index.html

在本例中，只修改了一个文件。回想一下，你生成了 index.html 和 navData.js。但显然生成的 navata.js 与 kubernetes/website仓库中已有的navData.js` 没有什么不同。

在 <web base> 目录下运行 git add 和 git commit 将提交修改。

将你的修改作为 pull request 提交到 kubernetes/website 仓库。跟踪你的 PR，并根据需要回应评审人的评论。继续跟踪你的 PR，直到它被合入。

在 PR 合入的几分钟后，你的修改将出现在[已发布的参考文档](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/)。

{{% /capture %}}

{{% capture whatsnext %}}

• 为 Kubernetes 组件和工具生成参考文档
• 为 kubectl 命令集生成参考文档
• 为 Kubernetes 联邦 API 生成参考文档

{{% /capture %}}