From c5b5d952a182c241ef7c6e34c7affe9b170e1437 Mon Sep 17 00:00:00 2001 From: Jeremy Wilken Date: Thu, 19 May 2016 16:33:36 -0500 Subject: [PATCH] fix links to swagger UI and add a section on swagger specs --- _data/reference.yml | 2 ++ docs/api.md | 8 ++++++-- docs/user-guide/volumes.md | 4 ++-- 3 files changed, 10 insertions(+), 4 deletions(-) diff --git a/_data/reference.yml b/_data/reference.yml index 38d83aa30a..3b9b864cc7 100644 --- a/_data/reference.yml +++ b/_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: diff --git a/docs/api.md b/docs/api.md index df19733cce..e466962df2 100644 --- a/docs/api.md +++ b/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 diff --git a/docs/user-guide/volumes.md b/docs/user-guide/volumes.md index 44b9313d1e..b1147980d5 100644 --- a/docs/user-guide/volumes.md +++ b/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