From a18d6674c0704d5bd10c52efa54a8a6d04252c36 Mon Sep 17 00:00:00 2001 From: "Haowei Cai (Roy)" Date: Wed, 11 Apr 2018 18:45:55 -0700 Subject: [PATCH] Document new OpenAPI endpoint (#8050) * Document new OpenAPI endpoint Document new OpenAPI endpoint and deprecation announcement for old endpoints. * Remove out-of-date swagger spec information Deprecation announcement is in line 29 * Update default behavior for endpoint HTTP headers --- docs/concepts/overview/kubernetes-api.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/concepts/overview/kubernetes-api.md b/docs/concepts/overview/kubernetes-api.md index 8e10dc2bcf..589133e9da 100644 --- a/docs/concepts/overview/kubernetes-api.md +++ b/docs/concepts/overview/kubernetes-api.md @@ -26,7 +26,23 @@ What constitutes a compatible change and how to change the API are detailed by t Complete API details are documented using [Swagger v1.2](http://swagger.io/) and [OpenAPI](https://www.openapis.org/). The Kubernetes apiserver (aka "master") exposes an API that can be used to retrieve the Swagger v1.2 Kubernetes API spec located at `/swaggerapi`. -Starting with Kubernetes 1.4, OpenAPI spec is also available at [`/swagger.json`](https://git.k8s.io/kubernetes/api/openapi-spec/swagger.json). While we are transitioning from Swagger v1.2 to OpenAPI (aka Swagger v2.0), some of the tools such as kubectl and swagger-ui are still using v1.2 spec. OpenAPI spec is in Beta as of Kubernetes 1.5. +Starting with Kubernetes 1.10, OpenAPI spec is served in a single `/openapi/v2` endpoint. The format-separated endpoints (`/swagger.json`, `/swagger-2.0.0.json`, `/swagger-2.0.0.pb-v1`, `/swagger-2.0.0.pb-v1.gz`) are deprecated and will get removed in Kubernetes 1.14. + +Requested format is specified by setting HTTP headers: + +Header | Possible Values +-- | -- +Accept | `application/json`, `application/com.github.proto-openapi.spec.v2@v1.0+protobuf` (the default content-type is `application/json` for `*/*` or not passing this header) +Accept-Encoding | `gzip` (not passing this header is acceptable) + +**Examples of getting OpenAPI spec**: + +Before 1.10 | Starting with Kubernetes 1.10 +-- | -- +GET /swagger.json | GET /openapi/v2 **Accept**: application/json +GET /swagger-2.0.0.pb-v1 | GET /openapi/v2 **Accept**: application/com.github.proto-openapi.spec.v2@v1.0+protobuf +GET /swagger-2.0.0.pb-v1.gz | GET /openapi/v2 **Accept**: application/com.github.proto-openapi.spec.v2@v1.0+protobuf **Accept-Encoding**: gzip + Kubernetes implements an alternative Protobuf based serialization format for the API that is primarily intended for intra-cluster communication, documented in the [design proposal](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/protobuf.md) and the IDL files for each schema are located in the Go packages that define the API objects.