基於OAS設計可擴展OpenAPI

時間 2019-11-08

標籤基於 oas 設計可擴展 openapi 简体版

原文原文鏈接

前言html

隨着互聯網行業的興起，開發模式已逐步轉換爲微服務自治：小團隊開發微服務，而後經過Restful接口相互調用。開發者們愈來愈渴望可以使用一種「官話」進行流暢的溝通，甚至實現多種編程語言系統的自動化交互。java

開放API戰略（Open API Initiativev）於2017年1月發表聲明，2月發佈實現草案，通過反覆討論，標準API規範OAS（OpenAPI-Specification）3.0版本在2017年6月誕生。git

本文經過對OAS 3.0的分析解讀，但願拋磚引玉，和你們一塊兒瞭解OAS如何定義一種機器和人都可以發現與識別的規範，使得OpenAPI消費者可以使用最小數量的實現邏輯來理解遠程服務。github

OpenAPI-Specification規範架構apache

OAS 3.0架構中將OpenAPI賦予瞭如下8個模塊的定義，其中黃色模塊爲必選字段，綠色模塊爲可選字段：編程

各個主要模塊工做流以下所示：json

如下重點說明用戶獲取OAS API信息的三個必選部分：後端

1.API基本信息api

用戶查詢獲取OpenAPI的基本定義及信息，涉及如下兩個模塊內容：數組

openapi

是否必選：必選

對象類型：String

相似於XML聲明（<?xml version="1.0"?> ），用於設定文件應該使用哪種規範進行解析。

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       #應用版本

2.目標服務器信息

用戶查詢獲取服務器的基本定義及信息，涉及如下模塊信息：

servers

是否必選：必選

對象類型：[Server Object]

這個模塊主要提供和目標服務器的鏈接信息，若是這個模塊沒有定義url，根據規範會自動生成一個url爲/的Server Object。

例如：

servers:

- url: https://development.gigantic-server.com/v1  #必選，

  description: Development server   #非必選，url描述

3.API路徑及定義

查詢API具體參數，涉及OAS剩餘的模塊，本文主要介紹paths和components模塊。

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

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: oauth2 
         flows: 
             implicit: 
                     authorizationUrl: http://example.org/api/oauth/dialog 
                     scopes: 
                         write:pets: modify pets in your account 
                         read:pets: read your pets

如何使用OAS 設計可擴展的OpenAPI

OpenAPI規範包含一組有關如何設計REST API的強制性準則，首推協議優先的方法，而非實現優先，所以須要首先設計API接口，而後實現協定接口的代碼。

如何實現一個優雅的API是一個很是具備挑戰性的工做，開發者須要在龐大的後端系統的支持下，經過合適的方式將API暴露出去，除去單詞拼寫，路徑設計等之外，設計優良的OpenAPI每每具備如下特性：

單一職責

單一職責是軟件工程中一條著名的原則，實際在設計API時應確保每一個API具備單一核心的職責，當某個API職責發生改變時不該該致使其餘API發生故障和風險。OAS中不一樣的API能夠在paths模塊中引用多個schema，當咱們設計新的API或者擴展原有API功能時，若是發現多個API屢次引用相同schema，需重點審視每一個API是否仍然保持單一職責。

抽象API

合適的抽象API 與業務無關的，更通用，並且方便擴展。具體的API接口設計能解決特定的問題，可是在系統的擴展性和廣泛適用性上則相應欠缺，所以須要針對特定的場景分析，避免over-designed（過分設計）和under-engineering（懶惰設計）。

舉個簡單的例子，咱們設計一個paths爲/dog的API，那麼這個API返回的是具體dog的相關信息，而若是咱們進行抽象設計一個paths爲/pet的API，將dog做爲參數配置在components的parameters中，這樣該API的擴展性進行了提高，後續擴展其餘寵物好比cat的業務能夠在不改變API路徑的基礎上進行開發，只須要更新component的parameters便可。

收斂API

提供給用戶的OpenAPI最好支持批量數據處理，而不是讓用戶一次一次地調用。經過考慮多個API間的關聯性，讓用戶體會到API的簡潔性。舉例來講，若是用戶有可能在調用 API2以前須要API1的結果，那麼API提供者應該把API1和API2進行包裝。這會減輕用戶的記憶負擔，API收斂須要符合最少知識的原則，做爲用戶應該對他所使用的系統有最少的瞭解，而不是過多介入到系統的細節中，所以在設計API時候，在知足用戶訴求的狀況下，components模塊字段越少越好。設計者每每容易在收斂API時候出現沒法保證單一職責的原則的狀況，好的設計須要在二者之間取得一個平衡，聚焦於最終的目的:讓使用者快好省的用起來。

擴展機制

在設計API時須要考慮將來可擴展性，爲後續API兼容歷史API提供支持。一方面便於開發者自身增長功能，另外一方面用戶也能參與進來，共建API生態。經過設計定義OAS，能夠方便的按照OAS架構設計出面向對象、擴展性良好的API。

版本控制

版本控制實際上是擴展的一部分，鑑於大量項目在版本控制方面都作的比較糟糕，諸如爲所欲爲的版本命名、先後格式不一致的版本設定、沒有規範的功能迭代，所以在大版本號不變的狀況下，須要保障API向前兼容。當API的大版本號改動時，意味着API總體有大的改動，極可能不兼容以前的API，同時能夠提醒用戶須要查詢API更新文檔進行適配，不然用戶可能在更新API以後出現各類各樣難以預測的故障。反之，若是修改小版本號則意味着這是個向前兼容的優化升級，用戶能夠在例行更新中採用新的API。這種和用戶約定好的默契，能夠激發用戶採用新版本的熱情，而不是永遠不升級依賴。

面向擴展開發

在經過OAS定義完相關信息以後，優雅的OpenAPI在開發過程當中應着重思考API的可配置性，API的實現應該面向修改開放的，所以須要將相關諸如參數校驗、字段長度等配置項進行抽取，在提供默認配置項的前提下可配置可修改，同時應當容許配置項的新增，例如引入java的可變參數類型等，這樣當OAS文檔進行修改時，能夠儘量的較少總體API實現的變更量。

以上列舉了優雅的OpenAPI所具備的部分特性，與其說OAS設計規範是一個強制的法則，不如說是一種引導式框架，開發者經過遵循規範從而實現高效的敏捷迭代。

當完成OpenAPI的設計開發以後，咱們須要將API託管到合適的平臺上進行能力開放，優秀的平臺減小API提供者的工做量，抽取公共能力使API提供者更加專一於業務功能開發。華爲雲的API網關集成了監控、流控、負載均衡等一系列功能，能夠爲開發者提供高性能、高可用的API 託管服務，實現我的、企業API能力的快速開放。

關於API網關的詳情，能夠點擊這裏免費體驗。

參考文獻：

《OpenAPI Specification》：https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#componentsObject

《Microsoft REST API Guidelines》：https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md

《API 設計》：https://docs.microsoft.com/zh-cn/azure/architecture/best-practices/api-design

《從達標到卓越 —— API 設計之道》：http://taobaofed.org/blog/2017/02/16/a-guide-to-api-design/