fix links to swagger UI and add a section on swagger specs

_data/reference.yml

@@ -24,6 +24,8 @@ toc:
     path: /docs/api-reference/v1/operations/
   - title: Kubernetes API Definitions
     path: /docs/api-reference/v1/definitions/
+  - title: Kubernetes API Swagger Spec
+    path: /kubernetes/third_party/swagger-ui/
 
 - title: Extensions API
   section:

docs/api.md

@@ -5,8 +5,6 @@ Primary system and API concepts are documented in the [User guide](/docs/user-gu
 
 Overall API conventions are described in the [API conventions doc](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/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/).
-
 Remote access to the API is discussed in the [access doc](/docs/admin/accessing-the-api).
 
 The Kubernetes API also serves as the foundation for the declarative configuration schema for the system. The [Kubectl](/docs/user-guide/kubectl/kubectl) command-line tool can be used to create, update, delete, and get API objects.
@@ -21,6 +19,12 @@ In our experience, any system that is successful needs to grow and change as new
 
 What constitutes a compatible change and how to change the API are detailed by the [API change document](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api_changes.md).
 
+## API Swagger definitions
+
+Complete API details are documented using [Swagger v1.2](http://swagger.io/). The Kubernetes apiserver (aka "master") exposes an API that can be used to retrieve the Swagger Kubernetes API spec, by default at located at `/swaggerapi`, and a UI to browse the API documentation at `/swagger-ui`.
+
+We also host a version of the [latest API documentation UI](http://kubernetes.io/kubernetes/third_party/swagger-ui/). This is updated with the latest release, so if you are using a different version of Kubernetes you will want to use the spec from your apiserver.
+
 ## API versioning
 
 To make it easier to eliminate fields or restructure resource representations, Kubernetes supports

docs/user-guide/volumes.md

@@ -38,9 +38,9 @@ medium that backs it, and the contents of it are determined by the particular
 volume type used.
 
 To use a volume, a pod specifies what volumes to provide for the pod (the
-[`spec.volumes`](http://kubernetes.io/third_party/swagger-ui/#!/v1/createPod)
+[`spec.volumes`](http://kubernetes.io/kubernetes/third_party/swagger-ui/#!/v1/createPod)
 field) and where to mount those into containers(the
-[`spec.containers.volumeMounts`](http://kubernetes.io/third_party/swagger-ui/#!/v1/createPod)
+[`spec.containers.volumeMounts`](http://kubernetes.io/kubernetes/third_party/swagger-ui/#!/v1/createPod)
 field).
 
 A process in a container sees a filesystem view composed from their Docker