OpenShift API Documentation
---------------------------
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`
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).