OpenAPI的新功能是什么

Open API 即開放 API，也稱開放平臺(tái)。 所謂的開放 API（OpenAPI）是服務(wù)型網(wǎng)站常見的一種應(yīng)用，網(wǎng)站的服務(wù)商將自己的網(wǎng)站服務(wù)封裝成一系列API（開放出去，供第三方開發(fā)者使用，這種行為就叫做開放網(wǎng)站的 API，所開放的 API 就被稱作 OpenAPI（開放 API ）。

在 Kubernetes 1.4，我們對(duì)目前的模型和操作進(jìn)行了升級(jí)，引入了 Open API 規(guī)范（在沒被捐獻(xiàn)給 Open API 之前被稱作 Swagger 2.0）支持的 Alpha 版本。從 Kubernetes 1.5 開始，OpenAPI 規(guī)范的支持已經(jīng)完備，能夠直接從 Kubernetes 源碼生成規(guī)范，對(duì)于模型和方法的任何變更，都會(huì)保障文檔和規(guī)范的完全同步。

新規(guī)范讓我們有了更好的 API 文檔，甚至還有了一個(gè) Python 客戶端。

這一模塊化的規(guī)范用 GroupVersion 進(jìn)行分隔，這一做法屬于未雨綢繆，我們想要讓不同的 API Server 使用不同的 GroupVersion。

規(guī)范的結(jié)構(gòu)在 Open API spec definition 中有解釋。我們用 operation 標(biāo)記 來拆分每個(gè) GroupVersion 并盡可能的豐富其中的模型、路徑、操作等信息。操作的參數(shù)、調(diào)用方法以及響應(yīng)都有文檔描述。

例如，獲取 Pod 信息的 OpenAPI 規(guī)范

{
...
 "paths": {"/api/v1/namespaces/{namespace}/pods/{name}": {
   "get": {
    "description": "read the specified Pod",
    "consumes": [
     "*/*"    ],
    "produces": [
     "application/json",
     "application/yaml",
     "application/vnd.kubernetes.protobuf"    ],
    "schemes": [
     "https"    ],
    "tags": [
     "core_v1"    ],
    "operationId": "readCoreV1NamespacedPod",
    "parameters": [
     {
      "uniqueItems": true,
      "type": "boolean",
      "description": "Should the export be exact.  Exact export maintains cluster-specific fields like 'Namespace'.",
      "name": "exact",
      "in": "query"     },
     {
      "uniqueItems": true,
      "type": "boolean",
      "description": "Should this value be exported.  Export strips fields that a user can not specify.",
      "name": "export",
      "in": "query"     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "schema": {
       "$ref": "#/definitions/v1.Pod"      }
     },
     "401": {
      "description": "Unauthorized"     }
    }
   },
…
}
…

有了這些信息，以及 kube-apiserver 的 URL，就可以據(jù)此來調(diào)用接口了（/api/v1/namespaces/{namespace}/pods/{name}），參數(shù)包括 name、exact 以及 export 等，調(diào)用結(jié)果會(huì)返回 Pod 信息?？蛻魩?kù)生成器也會(huì)使用這些信息來創(chuàng)建一個(gè) API 函數(shù)調(diào)用來讀取 Pod 信息。例如 Python 客戶端 能夠很簡(jiǎn)單的進(jìn)行如下調(diào)用：

from kubernetes import client
ret = client.CoreV1Api().read_namespaced_pod(name="pods_name", namespace="default")
https://gist.github.com/mbohlool/d5ec1dace27ef90cf742555c05480146

一個(gè)簡(jiǎn)化版的 read_namespaced_pod;Python Client：https://github.com/kubernetes-incubator/client-python還可以使用 Swagger-codegen 文檔生成器來根據(jù)這些信息生成文檔：

GET /api/v1/namespaces/{namespace}/pods/{name}
(readCoreV1NamespacedPod)read the specified Pod
Path parameters
name (required)
Path Parameter — name of the Pod
namespace (required)
Path Parameter — object name and auth scope, such as for teams and projects
Consumes
This API call consumes the following media types via the Content-Type request header:
*/*

Query parameters
pretty (optional)
Query Parameter — If 'true', then the output is pretty printed.
exact (optional)
Query Parameter — Should the export be exact. Exact export maintains cluster-specific fields like 'Namespace'.export (optional)
Query Parameter — Should this value be exported. Export strips fields that a user can not specify.
Return typev1.Pod

Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
application/json
application/yaml
application/vnd.kubernetes.protobuf
Responses
200
OK v1.Pod
401
Unauthorized

有兩種方式訪問 OpenAPI

從 kube-apiserver/swagger.json。這個(gè)文件會(huì)包含所有啟用的 GroupVersion 方法和模型，其中的內(nèi)容會(huì)是該 API Server 所對(duì)應(yīng)的最新版本。

Kubernetes 的 Github 倉(cāng)庫(kù)，可以訪問 master 或者其他指定的 Release。

有很多工具 能和這些 API 協(xié)同工作，例如可以用 swagger editor 來打開規(guī)范文件并渲染文檔，或者生成客戶端；還可以直接利用 swagger codegen 來生成文檔和客戶端。自動(dòng)生成的客戶端多數(shù)時(shí)候是開箱即用的。不過可能需要做一些登錄和 Kubernetes 相關(guān)的設(shè)置。