--- title: Generating Reference Documentation for the Kubernetes API content_type: task weight: 50 --- This page shows how to update the Kubernetes API reference documentation. The Kubernetes API reference documentation is built from the [Kubernetes OpenAPI spec](https://github.com/kubernetes/kubernetes/blob/master/api/openapi-spec/swagger.json) using the [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) generation code. If you find bugs in the generated documentation, you need to [fix them upstream](/docs/contribute/generate-ref-docs/contribute-upstream/). If you need only to regenerate the reference documentation from the [OpenAPI](https://github.com/OAI/OpenAPI-Specification) spec, continue reading this page. ## {{% heading "prerequisites" %}} {{< include "prerequisites-ref-docs.md" >}} ## Setting up the local repositories Create a local workspace and set your `GOPATH`. ```shell mkdir -p $HOME/ export GOPATH=$HOME/ ``` Get a local clone of the following repositories: ```shell go get -u github.com/kubernetes-sigs/reference-docs go get -u github.com/go-openapi/loads go get -u github.com/go-openapi/spec ``` If you don't already have the kubernetes/website repository, get it now: ```shell git clone https://github.com//website $GOPATH/src/github.com//website ``` Get a clone of the kubernetes/kubernetes repository as k8s.io/kubernetes: ```shell git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes ``` * The base directory of your clone of the [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository is `$GOPATH/src/k8s.io/kubernetes.` The remaining steps refer to your base directory as ``. * The base directory of your clone of the [kubernetes/website](https://github.com/kubernetes/website) repository is `$GOPATH/src/github.com//website.` The remaining steps refer to your base directory as ``. * The base directory of your clone of the [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) repository is `$GOPATH/src/github.com/kubernetes-sigs/reference-docs.` The remaining steps refer to your base directory as ``. ## Generating the API reference docs This section shows how to generate the [published Kubernetes API reference documentation](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/). ### Setting build variables * Set `K8S_ROOT` to ``. * Set `WEB_ROOT` to ``. * Set `K8S_RELEASE` to the version of the docs you want to build. For example, if you want to build docs for Kubernetes 1.17, set `K8S_RELEASE` to 1.17. For example: ```shell export WEB_ROOT=$(GOPATH)/src/github.com//website export K8S_ROOT=$(GOPATH)/src/k8s.io/kubernetes export K8S_RELEASE=1.17 ``` ### Creating versioned directory and fetching Open API spec The `updateapispec` build target creates the versioned build directory. After the directory is created, the Open API spec is fetched from the `` repository. These steps ensure that the version of the configuration files and Kubernetes Open API spec match the release version. The versioned directory name follows the pattern of `v_`. In the `` directory, run the following build target: ```shell cd make updateapispec ``` ### Building the API reference docs The `copyapi` target builds the API reference and copies the generated files to directories in ``. Run the following command in ``: ```shell cd make copyapi ``` Verify that these two files have been generated: ```shell [ -e "/gen-apidocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html" [ -e "/gen-apidocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js" ``` Go to the base of your local ``, and view which files have been modified: ```shell cd git status ``` The output is similar to: ``` static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/bootstrap.min.css static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/font-awesome.min.css static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/stylesheet.css static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/FontAwesome.otf static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.eot static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.svg static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.ttf static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.woff static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.woff2 static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/index.html static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/jquery.scrollTo.min.js static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/navData.js static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/scroll.js ``` ## Updating the API reference index pages When generating reference documentation for a new release, update the file, `/content/en/docs/reference/kubernetes-api/api-index.md` with the new version number. * Open `/content/en/docs/reference/kubernetes-api/api-index.md` for editing, and update the API reference version number. For example: ``` --- title: v1.17 --- [Kubernetes API v1.17](/docs/reference/generated/kubernetes-api/v1.17/) ``` * Open `/content/en/docs/reference/_index.md` for editing, and add a new link for the latest API reference. Remove the oldest API reference version. There should be five links to the most recent API references. ## Locally test the API reference Publish a local version of the API reference. Verify the [local preview](http://localhost:1313/docs/reference/generated/kubernetes-api/{{< param "version">}}/). ```shell cd git submodule update --init --recursive --depth 1 # if not already done make container-serve ``` ## Commit the changes In `` run `git add` and `git commit` to commit the change. Submit your changes as a [pull request](/docs/contribute/new-content/open-a-pr/) to the [kubernetes/website](https://github.com/kubernetes/website) repository. Monitor your pull request, and respond to reviewer comments as needed. Continue to monitor your pull request until it has been merged. ## {{% heading "whatsnext" %}} * [Generating Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/) * [Generating Reference Docs for Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/) * [Generating Reference Documentation for kubectl Commands](/docs/contribute/generate-ref-docs/kubectl/)