由於API對於我們的軟件運行方式至關重要，因此記錄我們的API對於確保我們大型IT組織中的每個人都了解正在發生的事情至關重要，這就是我們使用OpenAPI來幫助記錄API規范的原因。
在本文中，我將向你介紹OpenAPI規范和API-First開發原則。
OpenAPI規范
OpenAPI規范始於Swagger規范，經過Reverb Technologies和SmartBear等公司多年的發展，OpenAPI計划擁有該規范（捐贈之后），OpenAPI Initiative在GitHub上托管社區驅動的規范。
規范是一種與語言無關的格式，用於描述RESTful Web服務，應用程序可以解釋生成的文件，這樣才能生成代碼、生成文檔並根據其描述的服務創建模擬應用。
什么是API優先開發？
應用程序向雲環境這一演變趨勢為更好地集成服務和增加代碼重用提供了機會，只要擁有一個接口，然后通過該接口，其他服務的應用程序就可以與你的應用程序進行交互，這是向其他人公開你的功能，但是，開發API卻不應該是在開發后才公開功能。
API文檔應該是構建應用程序的基礎，這個原則正是API-First(API優先)開發的全部內容，你需要設計和創建描述新服務與外部世界之間交互的文檔，一旦建立了這些交互，就可以開發代碼邏輯來支持這些交互。讓我們來看看這種方法帶來的好處。
API-First如何使您的組織受益
當你的組織從API文檔開始時，這允許團隊在開發過程中更快地開始彼此交互。API文檔是應用程序與使用它的人之間的合同。
內部開發可以在API合同背后進行，而不會干擾使用它的人的努力，計划使用你的應用程序的團隊可以使用API規范來了解如何與你的應用程序進行交互，甚至在開發之前。他們還可以使用該文檔創建用於測試其應用程序的虛擬服務。
OpenAPI文檔的剖析
該規范的當前版本是3.0.1版，並在OpenAPI GitHub存儲庫中進行了詳細記錄。但是，如果你像我一樣，我更喜歡看一個規范的例子，而不是通過描述文檔描述每個可能的部分的明確的技術細節。
讓我們看一個描述服務API的簡單API文檔，它允許用戶創建，修改，檢索和刪除用戶首選項。您可以在SwaggerHub上完整地查看此API 。
OpenAPI文檔有三個必需的部分或對象：
1. openapi - OpenAPI規范版本的語義版本號
2. info - 有關API的元數據
3. paths - API的可用路徑和操作
你可以根據需要包含其他對象。其他對象包括安全性，服務器，標簽和組件。
openapi: 3.0.1 info: version: "1.0.0" title: 用戶指導API description: 這是一個支持用戶設置的創建，修改，檢索和刪除。 <p> |
openapi對象聲明了用於文檔的規范的版本。該版本對於用戶理解文檔的結構至關重要，更重要的是，對於可能為了驗證目的而獲取文檔或創建虛擬服務的任何工具，info對象提供有關API本身的基本信息。標題和版本是必填字段，我們可以選擇包含其他信息，例如說明，聯系和許可信息。
路徑對象
paths路徑對象是API文檔的核心。此對象詳細說明了可與應用程序交互的路徑，可用的方法以及這些交互包含的內容的詳細信息。該對象包括請求參數和預期結果：
paths:
/preference:
get:
summary: 根據ID發現用戶設置
description: 返回用戶設置
operationId: getPreferenceById
parameters:
- name: id
in: query
description: 這是返回一個用戶設置的ID
required: true
schema:
type: string
responses:
'200':
description: 請求成功
content:
application/json:
schema:
$ref: '#/components/schemas/Preference'
'400':
description: 無效 ID
'404':
description: 用戶設置沒有發現
<p>
|
上面的摘錄描述了按ID檢索用戶設置的GET請求路徑，這些屬性大多是不言自明的。值得注意的是HTTP 200響應的模式。$ ref屬性引用文件中其他位置的對象，它是用於多個路徑的描述：
#/components/schemas/Preference的結構如下：
components:
schemas:
Preference:
type: object
required:
- userId
- preferenceName
- status
properties:
userId:
type: string
format: uuid
preferenceName:
type: string
preferenceValue:
type: string
status:
type: string
description: Preference Status
enum:
- test
- enabled
- disabled
- delete
<p>
|
在另外一個地方定義組件並引用它，這種方式能讓我們重用相同的定義並使我們的OpenAPI合同更易於管理。
在swaggerhub有在線編輯器可以體驗。
