Add a README for api-reference docs and link to it instead of linking…

… to swagger-ui
lavalamp · Mar 16, 2016 · 2f6991c · 2f6991c
1 parent 067b132
commit 2f6991c
Show file tree

Hide file tree

Showing 5 changed files with 47 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -86,7 +86,7 @@ Kubernetes documentation is organized into several categories.
       or extensions, or modify the core Kubernetes code
     - in the [Kubernetes Developer Guide](docs/devel/README.md)
     - see also [notes on the API](docs/api.md)
-    - see also the [API object documentation](http://kubernetes.io/third_party/swagger-ui/), a
+    - see also the [API object documentation](docs/api-reference/README.md), a
       detailed description of all fields found in the core API objects
   - **Walkthroughs and examples**
     - hands-on introduction and example config files

diff --git a/docs/README.md b/docs/README.md
@@ -47,7 +47,7 @@ Documentation for other releases can be found at
 * The [Kubectl Command Line Interface](user-guide/kubectl/kubectl.md) is a detailed reference on
   the `kubectl` CLI.
 
-* The [API object documentation](http://kubernetes.io/third_party/swagger-ui/)
+* The [API object documentation](api-reference/README.md)
   is a detailed description of all fields found in core API objects.
 
 * An overview of the [Design of Kubernetes](design/)

diff --git a/docs/api-reference/README.md b/docs/api-reference/README.md
@@ -0,0 +1,42 @@
+<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
+
+<!-- BEGIN STRIP_FOR_RELEASE -->
+
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+
+<h2>PLEASE NOTE: This document applies to the HEAD of the source tree</h2>
+
+If you are using a released version of Kubernetes, you should
+refer to the docs that go with that version.
+
+Documentation for other releases can be found at
+[releases.k8s.io](http://releases.k8s.io).
+</strong>
+--
+
+<!-- END STRIP_FOR_RELEASE -->
+
+<!-- END MUNGE: UNVERSIONED_WARNING -->
+
+# API Reference
+
+Use the following reference docs to understand the kubernetes REST API for various API group versions:
+
+* v1: [operations](https://htmlpreview.github.io/?https://github.com/kubernetes/kubernetes/blob/HEAD/docs/api-reference/v1/operations.html), [model definitions](https://htmlpreview.github.io/?https://github.com/kubernetes/kubernetes/blob/HEAD/docs/api-reference/v1/definitions.html)
+* extensions/v1beta1: [operations](https://htmlpreview.github.io/?https://github.com/kubernetes/kubernetes/blob/HEAD/docs/api-reference/extensions/v1beta1/operations.html), [model definitions](https://htmlpreview.github.io/?https://github.com/kubernetes/kubernetes/blob/HEAD/docs/api-reference/extensions/v1beta1/definitions.html)
+* batch/v1: [operations](https://htmlpreview.github.io/?https://github.com/kubernetes/kubernetes/blob/HEAD/docs/api-reference/batch/v1/operations.html), [model definitions](https://htmlpreview.github.io/?https://github.com/kubernetes/kubernetes/blob/HEAD/docs/api-reference/batch/v1/definitions.html)
+* autoscaling/v1: [operations](https://htmlpreview.github.io/?https://github.com/kubernetes/kubernetes/blob/HEAD/docs/api-reference/autoscaling/v1/operations.html), [model definitions](https://htmlpreview.github.io/?https://github.com/kubernetes/kubernetes/blob/HEAD/docs/api-reference/autoscaling/v1/definitions.html)
+
+
+<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
+[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/api-reference/README.md?pixel)]()
+<!-- END MUNGE: GENERATED_ANALYTICS -->
diff --git a/docs/api.md b/docs/api.md
@@ -38,7 +38,7 @@ Primary system and API concepts are documented in the [User guide](user-guide/RE
 
 Overall API conventions are described in the [API conventions doc](devel/api-conventions.md).
 
-Complete API details are documented via [Swagger](http://swagger.io/). The Kubernetes apiserver (aka "master") exports an API that can be used to retrieve the [Swagger spec](https://github.com/swagger-api/swagger-spec/tree/master/schemas/v1.2) for the Kubernetes API, by default at `/swaggerapi`, and a UI you can use to browse the API documentation at `/swagger-ui`. We also periodically update a [statically generated UI](http://kubernetes.io/third_party/swagger-ui/).
+Complete API details are documented via [Swagger](http://swagger.io/). The Kubernetes apiserver (aka "master") exports an API that can be used to retrieve the [Swagger spec](https://github.com/swagger-api/swagger-spec/tree/master/schemas/v1.2) for the Kubernetes API, by default at `/swaggerapi`, and a UI you can use to browse the API documentation at `/swagger-ui`. We also host generated [API reference docs](api-reference/README.md).
 
 Remote access to the API is discussed in the [access doc](admin/accessing-the-api.md).
 

diff --git a/docs/devel/README.md b/docs/devel/README.md
@@ -83,7 +83,8 @@ Guide](../admin/README.md).
 
 ## Developing against the Kubernetes API
 
-* API objects are explained at [http://kubernetes.io/third_party/swagger-ui/](http://kubernetes.io/third_party/swagger-ui/).
+* The [REST API documentation](../api-reference/README.md) explains the REST
+  API exposed by apiserver.
 
 * **Annotations** ([docs/user-guide/annotations.md](../user-guide/annotations.md)): are for attaching arbitrary non-identifying metadata to objects.
   Programs that automate Kubernetes objects may use annotations to store small amounts of their state.