OpenAPI概述是怎樣的,針對這個問題,這篇文章詳細介紹了相對應(yīng)的分析和解答,希望可以幫助更多想解決這個問題的小伙伴找到更簡單易行的方法。
堅守“ 做人真誠 · 做事靠譜 · 口碑至上 · 高效敬業(yè) ”的價值觀,專業(yè)網(wǎng)站建設(shè)服務(wù)10余年為成都門窗定制小微創(chuàng)業(yè)公司專業(yè)提供成都企業(yè)網(wǎng)站定制營銷網(wǎng)站建設(shè)商城網(wǎng)站建設(shè)手機網(wǎng)站建設(shè)小程序網(wǎng)站建設(shè)網(wǎng)站改版,從內(nèi)容策劃、視覺設(shè)計、底層架構(gòu)、網(wǎng)頁布局、功能開發(fā)迭代于一體的高端網(wǎng)站建設(shè)服務(wù)。
通常所說的OpenAPI是指OpenAPI規(guī)范(OpenAPI Specification),簡稱OAS,該規(guī)范用于規(guī)范RESTful風(fēng)格的API描述方法。
我們有很多種方法來描述一個web服務(wù)的API,比如使用world文件描述,但這樣的API描述不夠通用。 OpenAPI規(guī)范定義了一種通用的接口描述方法,按照這個規(guī)范定義接口,不僅適合人閱讀,也方便程序處理。
OpenAPI規(guī)范的前身是Swagger規(guī)范,其由名為Swagger API
的項目發(fā)展而來。
2011年,美國的工程師Tony Tam
創(chuàng)建了Swagger API
項目,該項目由早期的規(guī)范和一系列工具組成,此時規(guī)范還稱為Swagger規(guī)范
。
該項目最初幾年發(fā)展并不順利,只有一些小公司和個人開發(fā)者認可該項目,同時業(yè)界也出現(xiàn)了一些競爭對手, 比如同樣用于描述API的RAML
,雖然此時Swagger規(guī)范
的熱度仍遠遠高于其競爭對手, 但這僅得益于Swagger API
項目的先發(fā)優(yōu)勢。同期出現(xiàn)的競爭對手擁有強大的背景和資金支持,長期發(fā)展下去Swagger API
項目必然落于下風(fēng),進而只能成為互聯(lián)網(wǎng)發(fā)展史上一個被人遺忘的詞條。
Swagger API
項目若要繼續(xù)發(fā)展,不僅需要資金支持,還需要諸如Google這樣的互聯(lián)網(wǎng)大廠認可,只有這樣Swagger規(guī)范
才有可能成為業(yè)界通用的規(guī)范。
在2015年,Swagger API
項目的創(chuàng)建者Tony Tam
跳槽到了SmartBear Software
公司,在該公司的支持下,Swagger API
項目取得了奠定未來格局的變化。
同樣是2015年,SmartBear Software
公司將Swagger規(guī)范
捐獻給Linux基金會,Linux基金會專門成立新的項目OpenAPI Initiative
用于托管該規(guī)范,新項目的創(chuàng)始成員包括Google、IBM和微軟等公司。通過該方式,Swagger規(guī)范
得到了互聯(lián)網(wǎng)大廠的支持并得以繼續(xù)發(fā)展。
接著,Swagger規(guī)范
從原Swagger API
項目中剝離出來,更名為OpenAPI規(guī)范
后托管到OpenAPI Initiative
項目,Swagger API
項目中仍保留了與該規(guī)范相關(guān)的工具。
自此,在Linux基金會的運作下,OpenAPI規(guī)范
逐漸成為業(yè)界事實上的標(biāo)準(zhǔn),而原Swagger API
項目的資助者SmartBear Software
公司則繼續(xù)運營與規(guī)范相關(guān)的工具產(chǎn)品,根據(jù)2017年的統(tǒng)計數(shù)據(jù),這些工具每日下載量高達10萬次。
當(dāng)SmartBear Software
公司將Swagger規(guī)范
捐獻給Linux基金會時,Swagger規(guī)范
版本為2.0,業(yè)界習(xí)慣上將使用該規(guī)范描述的API文件命名為swagger.json
,此時Swagger規(guī)范
2.0版本和OpenAPI規(guī)范
2.0版本是完全一致的,只是規(guī)范的一次重命名。
在Linux基金會的運作下,OpenAPI規(guī)范
繼續(xù)演進,并于2017年發(fā)布了3.0版本,該版本不僅支持使用JSON格式描述API還支持YAML格式,按照規(guī)范,使用該版本規(guī)范描述API的文件推薦命名為openapi.json
或openapi.yaml
。
schema常被簡單地譯為模式
,但它往往表示事物的組織和結(jié)構(gòu),比如數(shù)據(jù)庫的schema表示數(shù)據(jù)庫的組織和結(jié)構(gòu),同理OpenAPI規(guī)范
也定義了一組schema對象,用于表示一個完整的OpenAPI規(guī)范
文件。
每個版本的OpenAPI規(guī)范
會有不同的schema對象,由于Kubernetes(v1.18.0)仍在使用OpenAPI規(guī)范
2.0版本,所以本文僅介紹一點Kubernetes用到的schema對象,更詳細的內(nèi)容請查閱規(guī)范。
訪問kube-apiserver的/openapi/v2
接口即可獲取完整的接口描述文件,比如在本地集群中執(zhí)行如下命令:
[root@ecs-d8b6 ~]# curl localhost:8080/openapi/v2
該命令會輸出完整的接口描述文件。該文件中由一系列字段組成,每個字段均稱為一個schema對象,字段分為必選字段和可選字段。
swagger字段用于描述規(guī)范的版本,字段類型為string。比如Kubernetes的swagger字段如下所示:
{ "swagger": "2.0", ... }
該字段表明當(dāng)前API文檔采用的規(guī)范版本,主要用于相關(guān)工具識別并處理該文檔。
info字段用于描述API的基本信息,字段類型為Info Object
。 Info Object
類型包含以下兩個必須字段:
title:類型為string,表示應(yīng)用的名稱。
version:類型為string,表示應(yīng)用的版本。
比如,Kubernetes的info字段如下所示:
{ "info": { "title": "Kubernetes", "version": "v1.19.0" }, ... }
info字段表示了該文檔記錄的是Kubernetes的v1.19.0版本的接口。
paths字段用于描述API的各個端點及支持的操作,字段類型為Paths Object
。 Paths Object
類型又由Path Item Object
類型構(gòu)成,Kubernetes的端點/api
描述如下所示:
{ "paths": { "/api/": { "get": { "description": "get available API versions", "consumes": [ "application/json", "application/yaml", "application/vnd.kubernetes.protobuf" ], "produces": [ "application/json", "application/yaml", "application/vnd.kubernetes.protobuf" ], "schemes": [ "https" ], "tags": [ "core" ], "operationId": "getCoreAPIVersions", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/io.k8s.apimachinery.pkg.apis.meta.v1.APIVersions" } }, "401": { "description": "Unauthorized" } } } }, ... } }
從上面的信息可以看出端點(接口)/api/
支持get
操作,用consumes
表示該接口支持的媒體類型,用produces
表示該接口支持返回的媒體類型,用responses
表示可能的返回值。
其中$ref
表示引用自定義的另一個對象。
definitions字段用于定義一組被各個接口引用(消費或產(chǎn)生)的對象,類型為Definitions Object
。
{ "definitions": { "io.k8s.apimachinery.pkg.apis.meta.v1.APIVersions": { "description": "APIVersions lists the versions that are available, ...", "type": "object", "required": [ "versions", "serverAddressByClientCIDRs" ], "properties": { ... "kind": { "description": "Kind is a string value representing the REST resource ...", "type": "string" }, "serverAddressByClientCIDRs": { "description": "a map of client CIDR to server address that is serving this group. ...", "type": "array", "items": { "$ref": "#/definitions/io.k8s.apimachinery.pkg.apis.meta.v1.ServerAddressByClientCIDR" } }, "versions": { "description": "versions are the api versions that are available.", "type": "array", "items": { "type": "string" } } }, ... }, ... } }
簡單說來,使用definitions字段定義的字段可以被多個操作引用,從而達到復(fù)用的目的。需要引用其他對象時只需要使用$ref
指定復(fù)用的對象即可,如下所示:
"$ref": "#/definitions/對象名"
在上面infos字段中引用了對象io.k8s.apimachinery.pkg.apis.meta.v1.APIVersions
用于表示接口調(diào)用成功后的返回內(nèi)容,該對象表示一定會返回versions
和serverAddressByClientCIDRs
信息,實際調(diào)用成功后的輸出如下所示:
[root@ecs-d8b6 ~]# curl localhost:8080/api/ { "kind": "APIVersions", "versions": [ "v1" ], "serverAddressByClientCIDRs": [ { "clientCIDR": "0.0.0.0/0", "serverAddress": "localhost:6443" } ] }
關(guān)于OpenAPI概述是怎樣的問題的解答就分享到這里了,希望以上內(nèi)容可以對大家有一定的幫助,如果你還有很多疑惑沒有解開,可以關(guān)注創(chuàng)新互聯(lián)行業(yè)資訊頻道了解更多相關(guān)知識。
文章題目:OpenAPI概述是怎樣的
文章源于:http://bm7419.com/article6/gosiog.html
成都網(wǎng)站建設(shè)公司_創(chuàng)新互聯(lián),為您提供App開發(fā)、外貿(mào)網(wǎng)站建設(shè)、網(wǎng)站收錄、外貿(mào)建站、服務(wù)器托管、做網(wǎng)站
聲明:本網(wǎng)站發(fā)布的內(nèi)容(圖片、視頻和文字)以用戶投稿、用戶轉(zhuǎn)載內(nèi)容為主,如果涉及侵權(quán)請盡快告知,我們將會在第一時間刪除。文章觀點不代表本網(wǎng)站立場,如需處理請聯(lián)系客服。電話:028-86922220;郵箱:631063699@qq.com。內(nèi)容未經(jīng)允許不得轉(zhuǎn)載,或轉(zhuǎn)載時需注明來源: 創(chuàng)新互聯(lián)