This directory contains a Swagger API definition for the OpenShift and Kubernetes APIs. The swagger-spec directory is generated automatically, and the other directories contain content that is used to generate the official documentation.
When you add a new object or field to the REST API, you should do the following:
- Ensure all of your fields have the description tag
- Run
hack/update-swagger-spec.sh - If you've added a new object, add a simple description to
api/definitions/v1.objectname/description.adoc(object name is all lower case for your Kind)- For an example, see
api/definitions/v1.persistentvolumeclaim/description.adoc
- For an example, see
To generate the docs, you need gradle 2.2+ installed, then run
$ hack/gen-swagger-docs.sh
That will create docs into _output/local/docs/swagger/api/v1 and oapi/v1 for the Kube and OpenShift docs.
From openshift-docs you can generate these directly in one step - make the changes to the OpenShift origin repo (like adding descriptions or generating new swagger doc), then run
$ cd ../openshift-docs
$ rake import_api
This will invoke gen-swagger-docs.sh and import the API into rest_api/. After importing you'll need to add the correct adoc metadata to the top of kubernetes_v1.adoc and openshift_v1.adoc (pulls to automate that welcome).