OpenAPI規範入門

banq發表於2018-09-14
API
當我不寫文章時，我在一家大型軟體公司工作，我們擁有許多工程團隊，所有這些團隊都為複雜，多功能和高度可用的業務平臺的特定元素做出了貢獻。我們選擇了API-First方法來加速開發並增強領域之間的協作。

由於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 class="indent">


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 class="indent">


上面的摘錄描述了按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 class="indent">

在另外一個地方定義元件並引用它，這種方式能讓我們重用相同的定義並使我們的OpenAPI合同更易於管理。

在swaggerhub有線上編輯器可以體驗。

[img index=1]

Getting Started with the OpenAPI Specification · S

相關文章