基于OAS設(shè)計(jì)可擴(kuò)展OpenAPI的示例分析-創(chuàng)新互聯(lián)
這篇文章的內(nèi)容主要圍繞基于OAS設(shè)計(jì)可擴(kuò)展OpenAPI的示例分析進(jìn)行講述，文章內(nèi)容清晰易懂，條理清晰，非常適合新手學(xué)習(xí)，值得大家去閱讀。感興趣的朋友可以跟隨小編一起閱讀吧。希望大家通過這篇文章有所收獲！
創(chuàng)新互聯(lián)服務(wù)項(xiàng)目包括松原網(wǎng)站建設(shè)、松原網(wǎng)站制作、松原網(wǎng)頁制作以及松原網(wǎng)絡(luò)營(yíng)銷策劃等。多年來，我們專注于互聯(lián)網(wǎng)行業(yè)，利用自身積累的技術(shù)優(yōu)勢(shì)、行業(yè)經(jīng)驗(yàn)、深度合作伙伴關(guān)系等，向廣大中小型企業(yè)、政府機(jī)構(gòu)等提供互聯(lián)網(wǎng)行業(yè)的解決方案，松原網(wǎng)站推廣取得了明顯的社會(huì)效益與經(jīng)濟(jì)效益。目前，我們服務(wù)的客戶以成都為中心已經(jīng)輻射到松原省份的部分城市，未來相信會(huì)繼續(xù)擴(kuò)大服務(wù)區(qū)域并繼續(xù)獲得客戶的支持與信任！隨著互聯(lián)網(wǎng)行業(yè)的興起，開發(fā)模式已逐步轉(zhuǎn)換為微服務(wù)自治：小團(tuán)隊(duì)開發(fā)微服務(wù)，然后通過Restful接口相互調(diào)用。開發(fā)者們?cè)絹碓娇释軌蚴褂靡环N“官話”進(jìn)行流暢的溝通，甚至實(shí)現(xiàn)多種編程語言系統(tǒng)的自動(dòng)化交互。
開放API戰(zhàn)略（Open API Initiativev）于2017年1月發(fā)表聲明，2月發(fā)布實(shí)現(xiàn)草案，經(jīng)過反復(fù)討論， 標(biāo)準(zhǔn)API規(guī)范OAS（OpenAPI-Specification）3.0版本在2017年6月誕生。
OAS 3.0架構(gòu)中將OpenAPI賦予了以下8個(gè)模塊的定義，其中黃色模塊為必選字段，綠色模塊為可選字段：
各個(gè)主要模塊工作流如下所示：
以下重點(diǎn)說明用戶獲取使OAS API信息的三個(gè)必選部分：
1.1 API基本信息
用戶查詢獲取OpenAPI的基本定義及信息，涉及以下兩個(gè)模塊內(nèi)容：
l openapi
是否必選：必選
對(duì)象類型：String
類似于XML聲明（ ），用于設(shè)定文件應(yīng)該使用哪一種規(guī)范進(jìn)行解析。
l info
是否必選：必選
對(duì)象類型：Info Object
這個(gè)模塊主要提供API的元數(shù)據(jù)。
以下為一個(gè)Info Object樣例：
title: Sample Pet Store App #必須，應(yīng)用名稱
description: This is a sample server for apetstore. #應(yīng)用的描述
termsOfService: http://example.com/terms/ #應(yīng)用的服務(wù)條款連接
contact: #應(yīng)用提供商的聯(lián)系方式
name: API Support
url: http://www.example.com/support
email: support@example.com
license: #應(yīng)用所遵循的協(xié)議
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1 #應(yīng)用版本
1.2 目標(biāo)服務(wù)器信息
用戶查詢獲取服務(wù)器的基本定義及信息，涉及以下模塊信息：
servers
是否必選：必選
對(duì)象類型：[Server Object]
這個(gè)模塊主要提供和目標(biāo)服務(wù)器的連接信息，如果這個(gè)模塊沒有定義url，根據(jù)規(guī)范會(huì)自動(dòng)生成一個(gè)url為/的Server Object。
例如：
servers:
- url: https://development.gigantic-server.com/v1 #必選，
description: Development server #非必選，url描述
1.3 API路徑及定義
查詢API具體參數(shù)，涉及OAS剩余的模塊，本文主要介紹paths和components模塊。
l paths
是否必選：必選
對(duì)象類型：Paths Object
這個(gè)模塊主要提供OpenAPI所在的目標(biāo)服務(wù)器的連接信息，如果這個(gè)模塊沒有定義，根據(jù)規(guī)范會(huì)自動(dòng)生成一個(gè)url為/的Server Object。通過多級(jí)定義，分別確定API的paths/method，并且通過$ref引用comonents模塊中的定義，可以復(fù)用響應(yīng)碼等相關(guān)信息。對(duì)于攜帶body體的請(qǐng)求類型，requestBody可以提供example（或數(shù)組examples），這是非常靈活的（可以傳入一個(gè)完整的例子，一個(gè)參考，甚至是一個(gè)URL的例子）。
例如：
/pets: #URL
get: #方法，get/post/..
description: Returns all pets . #描述
responses: #響應(yīng)模塊
'200': #返回碼為200，可以使用通配符定義響應(yīng)
description: A list of pets. #響應(yīng)描述
content: #Content字段
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/pet' #引用componets
l components
是否必選：非必選
對(duì)象類型：Components Object
這個(gè)模塊主要提供每個(gè)OpenAPI自定義的字段定義，這部分定義的對(duì)象往往被paths中具體API進(jìn)行引用：
? 響應(yīng) responses
? 參數(shù) parameters
? 示例 examples
? 請(qǐng)求體 requestBodies
? 標(biāo)題 headers
? 鏈接 links
? 回調(diào) callbacks
? 模式 schemas
? 安全體系 securitySchemes
以下為一個(gè)Components Object樣例：
components:
schemas: #協(xié)議定義
Category:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
Tag:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
parameters: #參數(shù)定義
skipParam:
name: skip
in: query
description: number of items to skip
required: true
schema:
type: integer
format: int32
limitParam:
name: limit
in: query
description: max records to return
required: true
schema:
type: integer
format: int32
responses: #返回信息定義
NotFound:
description: Entity not found.
IllegalInput:
description: Illegal input for operation.
GeneralError:
description: General Error
content:
application/json:
schema:
$ref: '#/components/schemas/GeneralError'
securitySchemes:
api_key:
type: apiKey
name: api_key
in: header
petstore_auth: #認(rèn)證定義
type: oauth3
flows:
implicit:
authorizationUrl: http://example.org/api/oauth/dialog
scopes:
write:pets: modify pets in your account
read:pets: read your pets
2 如何使用OAS 設(shè)計(jì)可擴(kuò)展的OpenAPI
OpenAPI規(guī)范包含一組有關(guān)如何設(shè)計(jì)REST API的強(qiáng)制性準(zhǔn)則，首推協(xié)議優(yōu)先的方法，而非實(shí)現(xiàn)優(yōu)先，因此需要首先設(shè)計(jì)API接口，然后實(shí)現(xiàn)協(xié)定接口的代碼。
如何實(shí)現(xiàn)一個(gè)優(yōu)雅的API是一個(gè)非常具有挑戰(zhàn)性的工作，開發(fā)者需要在龐大的后端系統(tǒng)的支持下，通過合適的方式將API暴露出去，除去單詞拼寫，路徑設(shè)計(jì)等以外，設(shè)計(jì)優(yōu)良的OpenAPI往往具有以下特性：
l 單一職責(zé)
單一職責(zé)是軟件工程中一條著名的原則，實(shí)際在設(shè)計(jì)API時(shí)應(yīng)確保每個(gè)API具有單一核心的職責(zé)，當(dāng)某個(gè)API職責(zé)發(fā)生改變時(shí)不應(yīng)該導(dǎo)致其他API發(fā)生故障和風(fēng)險(xiǎn)。OAS中不同的API可以在paths模塊中引用多個(gè)schema，當(dāng)我們?cè)O(shè)計(jì)新的API或者擴(kuò)展原有API功能時(shí)，如果發(fā)現(xiàn)多個(gè)API多次引用相同schema，需重點(diǎn)審視每個(gè)API是否仍然保持單一職責(zé)。
l 抽象API
合適的抽象API 與業(yè)務(wù)無關(guān)的，更通用，而且方便擴(kuò)展。 具體的API接口設(shè)計(jì)能解決特定的問題，但是在系統(tǒng)的擴(kuò)展性和普遍適用性上則相應(yīng)欠缺，因此需要針對(duì)特定的場(chǎng)景分析，避免over-designed（過度設(shè)計(jì)）和under-engineering（懶惰設(shè)計(jì)）。
舉個(gè)簡(jiǎn)單的例子，我們?cè)O(shè)計(jì)一個(gè)paths為/dog的API，那么這個(gè)API返回的是具體dog的相關(guān)信息，而如果我們進(jìn)行抽象設(shè)計(jì)一個(gè)paths為/pet的API，將dog作為參數(shù)配置在components的parameters中，這樣該API的擴(kuò)展性進(jìn)行了提升，后續(xù)擴(kuò)展其他寵物比如cat的業(yè)務(wù)可以在不改變API路徑的基礎(chǔ)上進(jìn)行開發(fā)，只需要更新component的parameters即可。
l 收斂API
提供給用戶的OpenAPI最好支持批量數(shù)據(jù)處理，而不是讓用戶一次一次地調(diào)用。通過考慮多個(gè)API間的關(guān)聯(lián)性，讓用戶體會(huì)到API的簡(jiǎn)潔性。舉例來說，如果用戶有可能在調(diào)用 API2之前需要API1的結(jié)果，那么API提供者應(yīng)該把API1和API2進(jìn)行包裝。這會(huì)減輕用戶的記憶負(fù)擔(dān)，API收斂需要符合最少知識(shí)的原則，作為用戶應(yīng)該對(duì)他所使用的系統(tǒng)有最少的了解，而不是過多介入到系統(tǒng)的細(xì)節(jié)中，因此在設(shè)計(jì)API時(shí)候，在滿足用戶訴求的情況下，components模塊字段越少越好。設(shè)計(jì)者往往容易在收斂API時(shí)候出現(xiàn)無法保證單一職責(zé)的原則的情況，好的設(shè)計(jì)需要在兩者之間取得一個(gè)平衡，聚焦于最終的目的:讓使用者快好省的用起來。
l 擴(kuò)展機(jī)制
在設(shè)計(jì)API時(shí)需要考慮未來可擴(kuò)展性，為后續(xù)API兼容歷史API提供支持。一方面便于開發(fā)者自身增加功能，另一方面用戶也能參與進(jìn)來，共建API生態(tài)。通過設(shè)計(jì)定義OAS，可以方便的按照OAS架構(gòu)設(shè)計(jì)出面向?qū)ο蟆U(kuò)展性良好的API。
l 版本控制
版本控制其實(shí)是擴(kuò)展的一部分，鑒于大量項(xiàng)目在版本控制方面都做的比較糟糕，諸如隨心所欲的版本命名、前后格式不一致的版本設(shè)定、沒有規(guī)范的功能迭代，因此在大版本號(hào)不變的情況下，需要保障API向前兼容。當(dāng)API的大版本號(hào)改動(dòng)時(shí)，意味著API整體有大的改動(dòng)，很可能不兼容之前的API，同時(shí)可以提醒用戶需要查詢API更新文檔進(jìn)行適配，否則用戶可能在更新API之后出現(xiàn)各種各樣難以預(yù)測(cè)的故障。反之，如果修改小版本號(hào)則意味著這是個(gè)向前兼容的優(yōu)化升級(jí)，用戶可以在例行更新中采用新的API。這種和用戶約定好的默契，可以激發(fā)用戶采用新版本的熱情，而不是永遠(yuǎn)不升級(jí)依賴。
l 面向擴(kuò)展開發(fā)
在通過OAS定義完相關(guān)信息之后，優(yōu)雅的OpenAPI在開發(fā)過程中應(yīng)著重思考API的可配置性，API的實(shí)現(xiàn)應(yīng)該面向修改開放的，因此需要將相關(guān)諸如參數(shù)校驗(yàn)、字段長(zhǎng)度等配置項(xiàng)進(jìn)行抽取，在提供默認(rèn)配置項(xiàng)的前提下可配置可修改，同時(shí)應(yīng)當(dāng)允許配置項(xiàng)的新增，例如引入java的可變參數(shù)類型等，這樣當(dāng)OAS文檔進(jìn)行修改時(shí)，可以盡可能的較少整體API實(shí)現(xiàn)的變動(dòng)量。
以上列舉了優(yōu)雅的OpenAPI所具有的部分特性，與其說OAS設(shè)計(jì)規(guī)范是一個(gè)強(qiáng)制的法則，不如說是一種引導(dǎo)式框架，開發(fā)者通過遵循規(guī)范從而實(shí)現(xiàn)高效的敏捷迭代。
當(dāng)完成OpenAPI的設(shè)計(jì)開發(fā)之后，我們需要將API托管到合適的平臺(tái)上進(jìn)行能力開放，優(yōu)秀的平臺(tái)減少API提供者的工作量，抽取公共能力使API提供者更加專注于業(yè)務(wù)功能開發(fā)。華為云的API網(wǎng)關(guān)集成了監(jiān)控、流控、負(fù)載均衡等一系列功能，可以為開發(fā)者提供高性能、高可用的API 托管服務(wù)，實(shí)現(xiàn)個(gè)人、企業(yè)API能力的快速開放。
感謝你的閱讀，相信你對(duì)“基于OAS設(shè)計(jì)可擴(kuò)展OpenAPI的示例分析”這一問題有一定的了解，快去動(dòng)手實(shí)踐吧，如果想了解更多相關(guān)知識(shí)點(diǎn)，可以關(guān)注創(chuàng)新互聯(lián)-成都網(wǎng)站建設(shè)公司網(wǎng)站！小編會(huì)繼續(xù)為大家?guī)砀玫奈恼拢?/p>
網(wǎng)頁標(biāo)題：基于OAS設(shè)計(jì)可擴(kuò)展OpenAPI的示例分析-創(chuàng)新互聯(lián)
路徑分享：http://m.jiaotiyi.com/article/cegoej.html