whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update swagger/openapi descriptions (#12279)

Browse Source
This commit is contained in:
Jordan Liggitt
2019-01-19 05:49:49 -05:00
committed by Kubernetes Prow Robot
parent 3a4379d995
commit 777e085a97
2 changed files with 13 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/concepts/overview/kubernetes-api.md
+10 -5
View File
@@ -33,17 +33,19 @@ What constitutes a compatible change and how to change the API are detailed by t
## OpenAPI and Swagger definitions
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`.
Complete API details are documented using [OpenAPI](https://www.openapis.org/).
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:
Starting with Kubernetes 1.10, the Kubernetes API server serves an OpenAPI spec via the `/openapi/v2` endpoint.
The 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)
Prior to 1.14, format-separated endpoints (`/swagger.json`, `/swagger-2.0.0.json`, `/swagger-2.0.0.pb-v1`, `/swagger-2.0.0.pb-v1.gz`)
serve the OpenAPI spec in different formats. These endpoints are deprecated, and will be removed in Kubernetes 1.14.
**Examples of getting OpenAPI spec**:
Before 1.10 | Starting with Kubernetes 1.10
@@ -52,9 +54,12 @@ 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.
Prior to 1.14, the Kubernetes apiserver also exposes an API that can be used to retrieve
the [Swagger v1.2](http://swagger.io/) Kubernetes API spec at `/swaggerapi`.
This endpoint is deprecated, and will be removed in Kubernetes 1.14.
## API versioning
To make it easier to eliminate fields or restructure resource representations, Kubernetes supports
content/en/docs/reference/access-authn-authz/abac.md
+3 -4
View File
@@ -82,10 +82,9 @@ resource, and nonResourcePath properties set to `"*"`.
## Kubectl
Kubectl uses the `/api` and `/apis` endpoints of api-server to negotiate
client/server versions. To validate objects sent to the API by create/update
operations, kubectl queries certain swagger resources. For API version `v1`
those would be `/swaggerapi/api/v1` & `/swaggerapi/experimental/v1`.
Kubectl uses the `/api` and `/apis` endpoints of api-server to discover
served resource types, and validates objects sent to the API by create/update
operations using schema information located at `/openapi/v2`.
When using ABAC authorization, those special resources have to be explicitly
exposed via the `nonResourcePath` property in a policy (see [examples](#examples) below):