Skip to content
Yet another developer blog

OpenShift OpenAPI reference documentation generator

This tool generates documentation for the OpenShift OpenAPI specification for a running a cluster. The APIs included in the OpenAPI spec file are specific to the cluster from which the spec originates.

(If you want to immediately access the OpenShift API reference documentation, it is available as part of the official OpenShift Container Platform documentation.)

Configuration format

The configuration supports the following keys. Only uncommented keys are supported in the current release.

version: 2
outputDir: build
#apisToHide: []
apiMap: []

The apiMap key specifies an array of nested objects defining OpenShift APIs, with each object describing a related set of APIs.

Every key is required.

The values for the keys kind, group, and version are found in the output of oc api-resources on recent versions of OpenShift based on Kubernetes v1.20. For 'core' APIs, such as the Pod API, no group is specified as the group internally is empty.

- name: Authorization APIs
- kind: LocalResourceAccessReview
version: v1
- name: Autoscale APIs
- kind: ClusterAutoscaler
version: v1

How to install

This tool is written in JavaScript and depends on Node.js to run.



npm i -g @jboxman/openshift-apidocs-gen

CLI help

A list of commands and expected parameters is available from the tool itself:

openshift-apidocs-gen --help
Usage: openshift-apidocs-gen [options] [command]
-h, --help display help for command
build [options] <oApiSpecFile> Build the AsciiDoc source for the OpenShift API reference documentation
topic-map [options] Output YAML to stdout suitable for inclusion in an AsciiBinder _topic_map.yml file
changelog [options] <oApiSpecFile> Output a changelog to stdout for an `apiMap`
create-resources <oApiSpecFile> Output an `apiMap` array in YAML to stdout
help [command] display help for command

Typical usage

The following procedure reflects typical usage. For each new release of OpenShift, the apiMap must be adjusted accordingly as APIs are added and API versions incremented, or APIs are dropped.



  1. Log in to an OpenShift cluster with cluster-admin privileges.

  2. Run oc get --raw /openapi/v2 | jq . > openapi.json.

  3. Create an empty configuration:

    echo "version: 2
    outputDir: build
    apisToHide: []
    apiMap:" > config.yaml
  4. Generate an API map:

    openshift-apidocs-gen create-resources openapi.json >> config.yaml
  5. Generate the API docs:

    openshift-apidocs-gen build -c config.yaml openapi.json
  6. Build the HTML documentation, such as with the following command:

    find build -type f -name '*.adoc' | xargs -L1 -I^ -P1 asciidoctor -a toc -d book ^

Known issues

For known issues, refer to GitHub.