共計 4754 個字符，預計需要花費 12 分鐘才能閱讀完成。
這篇文章的內容主要圍繞基于 OAS 設計可擴展 OpenAPI 的示例分析進行講述，文章內容清晰易懂，條理清晰，非常適合新手學習，值得大家去閱讀。感興趣的朋友可以跟隨丸趣 TV 小編一起閱讀吧。希望大家通過這篇文章有所收獲！
隨著互聯網行業的興起，開發模式已逐步轉換為微服務自治：小團隊開發微服務，然后通過 Restful 接口相互調用。開發者們越來越渴望能夠使用一種“官話”進行流暢的溝通，甚至實現多種編程語言系統的自動化交互。
開放 API 戰略（Open API Initiativev）于 2017 年 1 月發表聲明，2 月發布實現草案，經過反復討論，
標準 API 規范 OAS（OpenAPI-Specification）3.0 版本在 2017 年 6 月誕生。
OAS 3.0 架構中將 OpenAPI 賦予了以下 8 個模塊的定義，其中黃色模塊為必選字段，綠色模塊為可選字段：
各個主要模塊工作流如下所示：
以下重點說明用戶獲取使 OAS API 信息的三個必選部分：
1.1 API 基本信息
用戶查詢獲取 OpenAPI 的基本定義及信息，涉及以下兩個模塊內容：
l
openapi
是否必選：必選
對象類型：String
類似于 XML 聲明（?xml version= 1.0 ?
），用于設定文件應該使用哪一種規范進行解析。
l
info
是否必選：必選
對象類型：Info Object
這個模塊主要提供 API 的元數據。
以下為一個 Info Object 樣例：
title: Sample Pet Store App #必須，應用名稱
description: This is a sample server for apetstore. #應用的描述
termsOfService: http://example.com/terms/ #應用的服務條款連接
contact: #應用提供商的聯系方式
name: API Support
url: http://www.example.com/support
email: support@example.com
license: #應用所遵循的協議
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1 #應用版本
1.2
目標服務器信息
用戶查詢獲取服務器的基本定義及信息，涉及以下模塊信息：
servers
是否必選：必選
對象類型：[Server Object]
這個模塊主要提供和目標服務器的連接信息，如果這個模塊沒有定義 url，根據規范會自動生成一個 url 為 / 的 Server Object。
例如：
servers:
– url: https://development.gigantic-server.com/v1 #必選，
description: Development server #非必選，url 描述
1.3 API 路徑及定義
查詢 API 具體參數，涉及 OAS 剩余的模塊，本文主要介紹 paths 和 components 模塊。
l
paths
是否必選：必選
對象類型：Paths Object
這個模塊主要提供 OpenAPI 所在的目標服務器的連接信息，如果這個模塊沒有定義，根據規范會自動生成一個 url 為 / 的 Server Object。通過多級定義，分別確定 API 的 paths/method，并且通過 $ref 引用 comonents 模塊中的定義，可以復用響應碼等相關信息。對于攜帶 body 體的請求類型，requestBody 可以提供 example（或數組 examples），這是非常靈活的（可以傳入一個完整的例子，一個參考，甚至是一個 URL 的例子）。
例如：
/pets: #URL
get: #方法，get/post/..
description: Returns all pets . #描述
responses: #響應模塊
200 : #返回碼為 200，可以使用通配符定義響應
description: A list of pets. #響應描述
content: #Content 字段
application/json:
schema:
type: array
items:
$ref: #/components/schemas/pet #引用 componets
l
components
是否必選：非必選
對象類型：Components Object
這個模塊主要提供每個 OpenAPI 自定義的字段定義，這部分定義的對象往往被 paths 中具體 API 進行引用：
?
responses
?
parameters
?
examples
?
requestBodies
?
headers
?
links
?
callbacks
?
schemas
?
securitySchemes
以下為一個 Components Object 樣例：
components:
schemas: #協議定義
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: #參數定義
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: # 認證定義
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
設計可擴展的 OpenAPI
OpenAPI 規范包含一組有關如何設計 REST API 的強制性準則，首推協議優先的方法，而非實現優先，因此需要首先設計 API 接口，然后實現協定接口的代碼。
如何實現一個優雅的 API 是一個非常具有挑戰性的工作，開發者需要在龐大的后端系統的支持下，通過合適的方式將 API 暴露出去，除去單詞拼寫，路徑設計等以外，設計優良的 OpenAPI 往往具有以下特性：
l
單一職責
單一職責是軟件工程中一條著名的原則，實際在設計 API 時應確保每個 API 具有單一核心的職責，當某個 API 職責發生改變時不應該導致其他 API 發生故障和風險。OAS 中不同的 API 可以在 paths 模塊中引用多個 schema，當我們設計新的 API 或者擴展原有 API 功能時，如果發現多個 API 多次引用相同 schema，需重點審視每個 API 是否仍然保持單一職責。
l
抽象 API
合適的抽象 API
與業務無關的，更通用，而且方便擴展。
具體的 API 接口設計能解決特定的問題，但是在系統的擴展性和普遍適用性上則相應欠缺，因此需要針對特定的場景分析，避免 over-designed（過度設計）和 under-engineering（懶惰設計）。
舉個簡單的例子，我們設計一個 paths 為 /dog 的 API，那么這個 API 返回的是具體 dog 的相關信息，而如果我們進行抽象設計一個 paths 為 /pet 的 API，將 dog 作為參數配置在 components 的 parameters 中，這樣該 API 的擴展性進行了提升，后續擴展其他寵物比如 cat 的業務可以在不改變 API 路徑的基礎上進行開發，只需要更新 component 的 parameters 即可。
l
收斂 API
提供給用戶的 OpenAPI 最好支持批量數據處理，而不是讓用戶一次一次地調用。通過考慮多個 API 間的關聯性，讓用戶體會到 API 的簡潔性。舉例來說，如果用戶有可能在調用
API2 之前需要 API1 的結果，那么 API 提供者應該把 API1 和 API2 進行包裝。這會減輕用戶的記憶負擔，API 收斂需要符合最少知識的原則，作為用戶應該對他所使用的系統有最少的了解，而不是過多介入到系統的細節中，因此在設計 API 時候，在滿足用戶訴求的情況下，components 模塊字段越少越好。設計者往往容易在收斂 API 時候出現無法保證單一職責的原則的情況，好的設計需要在兩者之間取得一個平衡，聚焦于最終的目的: 讓使用者快好省的用起來。
l
擴展機制
在設計 API 時需要考慮未來可擴展性，為后續 API 兼容歷史 API 提供支持。一方面便于開發者自身增加功能，另一方面用戶也能參與進來，共建 API 生態。通過設計定義 OAS，可以方便的按照 OAS 架構設計出面向對象、擴展性良好的 API。
l
版本控制
版本控制其實是擴展的一部分，鑒于大量項目在版本控制方面都做的比較糟糕，諸如隨心所欲的版本命名、前后格式不一致的版本設定、沒有規范的功能迭代，因此在大版本號不變的情況下，需要保障 API 向前兼容。當 API 的大版本號改動時，意味著 API 整體有大的改動，很可能不兼容之前的 API，同時可以提醒用戶需要查詢 API 更新文檔進行適配，否則用戶可能在更新 API 之后出現各種各樣難以預測的故障。反之，如果修改小版本號則意味著這是個向前兼容的優化升級，用戶可以在例行更新中采用新的 API。這種和用戶約定好的默契，可以激發用戶采用新版本的熱情，而不是永遠不升級依賴。
l
面向擴展開發
在通過 OAS 定義完相關信息之后，優雅的 OpenAPI 在開發過程中應著重思考 API 的可配置性，API 的實現應該面向修改開放的，因此需要將相關諸如參數校驗、字段長度等配置項進行抽取，在提供默認配置項的前提下可配置可修改，同時應當允許配置項的新增，例如引入 java 的可變參數類型等，這樣當 OAS 文檔進行修改時，可以盡可能的較少整體 API 實現的變動量。
以上列舉了優雅的 OpenAPI 所具有的部分特性，與其說 OAS 設計規范是一個強制的法則，不如說是一種引導式框架，開發者通過遵循規范從而實現高效的敏捷迭代。
當完成 OpenAPI 的設計開發之后，我們需要將 API 托管到合適的平臺上進行能力開放，優秀的平臺減少 API 提供者的工作量，抽取公共能力使 API 提供者更加專注于業務功能開發。華為云的 API 網關集成了監控、流控、負載均衡等一系列功能，可以為開發者提供高性能、高可用的 API
托管服務，實現個人、企業 API 能力的快速開放。
感謝你的閱讀，相信你對“基于 OAS 設計可擴展 OpenAPI 的示例分析”這一問題有一定的了解，快去動手實踐吧，如果想了解更多相關知識點，可以關注丸趣 TV 網站！丸趣 TV 小編會繼續為大家帶來更好的文章！
