mirror of
https://github.com/kubernetes/kubernetes.git
synced 2026-02-16 17:28:07 -05:00
7ce879d16f
This PR adds missing OpenAPI vendor extension documentation for the following: x-kubernetes-list-map-keys The provided documentation includes simple additions to api/openapi-spec/README.md with similar format to present documentation. Fixes issue #131724
88 lines
2.4 KiB
Markdown
88 lines
2.4 KiB
Markdown
# Kubernetes's OpenAPI Specification
|
|
|
|
This folder contains an [OpenAPI specification](https://github.com/OAI/OpenAPI-Specification) for Kubernetes API.
|
|
|
|
## Vendor Extensions
|
|
|
|
Kubernetes extends OpenAPI using these extensions. Note the version that
|
|
extensions have been added.
|
|
|
|
### `x-kubernetes-group-version-kind`
|
|
|
|
Operations and Definitions may have `x-kubernetes-group-version-kind` if they
|
|
are associated with a [kubernetes resource](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources).
|
|
|
|
|
|
For example:
|
|
|
|
``` json
|
|
"paths": {
|
|
...
|
|
"/api/v1/namespaces/{namespace}/pods/{name}": {
|
|
...
|
|
"get": {
|
|
...
|
|
"x-kubernetes-group-version-kind": {
|
|
"group": "",
|
|
"version": "v1",
|
|
"kind": "Pod"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### `x-kubernetes-action`
|
|
|
|
Operations and Definitions may have `x-kubernetes-action` if they
|
|
are associated with a [kubernetes resource](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources).
|
|
Action can be one of `get`, `list`, `put`, `patch`, `post`, `delete`, `deletecollection`, `watch`, `watchlist`, `proxy`, or `connect`.
|
|
|
|
|
|
For example:
|
|
|
|
``` json
|
|
"paths": {
|
|
...
|
|
"/api/v1/namespaces/{namespace}/pods/{name}": {
|
|
...
|
|
"get": {
|
|
...
|
|
"x-kubernetes-action": "list"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### `x-kubernetes-list-map-keys`
|
|
|
|
Operations and Definitions may have `x-kubernetes-list-maps-keys` if they
|
|
are associated with a [kubernetes resource](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources). `x-kubernetes-list-type` = `map` specifies field names inside each list element to serve as unique keys for the list-as-map.
|
|
|
|
**For example:**
|
|
|
|
```json
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"servers": {
|
|
"type": "array",
|
|
"x-kubernetes-list-type": "map",
|
|
"x-kubernetes-list-map-keys": ["name"],
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"name": { "type": "string" },
|
|
"address": { "type": "string" }
|
|
},
|
|
"required": ["name"]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### `x-kubernetes-patch-strategy` and `x-kubernetes-patch-merge-key`
|
|
|
|
Some of the definitions may have these extensions. For more information about PatchStrategy and PatchMergeKey see
|
|
[strategic-merge-patch](https://git.k8s.io/community/contributors/devel/sig-api-machinery/strategic-merge-patch.md).
|