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.
The configuration supports the following keys. Only uncommented keys are supported in the current release.
version: 2outputDir: build#apisToHide: apiMap: 
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
version are found in the output
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 APIsresources:- kind: LocalResourceAccessReviewgroup: authorization.openshift.ioversion: v1- name: Autoscale APIsresources:- kind: ClusterAutoscalergroup: autoscaling.openshift.ioversion: v1
How to install
- NodeJS >= 12
npm i -g @jboxman/openshift-apidocs-gen
A list of commands and expected parameters is available from the tool itself:
openshift-apidocs-gen --helpUsage: openshift-apidocs-gen [options] [command]Options:-h, --help display help for commandCommands:build [options] <oApiSpecFile> Build the AsciiDoc source for the OpenShift API reference documentationtopic-map [options] Output YAML to stdout suitable for inclusion in an AsciiBinder _topic_map.yml filechangelog [options] <oApiSpecFile> Output a changelog to stdout for an `apiMap`create-resources <oApiSpecFile> Output an `apiMap` array in YAML to stdouthelp [command] display help for command
The following procedure reflects typical usage. For each new release of
apiMap must be adjusted accordingly as APIs are added and API
versions incremented, or APIs are dropped.
Log in to an OpenShift cluster with
oc get --raw /openapi/v2 | jq . > openapi.json.
Create an empty configuration:echo "version: 2outputDir: buildapisToHide: apiMap:" > config.yaml
Generate an API map:openshift-apidocs-gen create-resources openapi.json >> config.yaml
Generate the API docs:openshift-apidocs-gen build -c config.yaml openapi.json
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 ^
For known issues, refer to GitHub.