基於OAS設計可擴展OpenAPI

隨着互聯網行業的興起，開發模式已逐步轉換爲微服務自治：小團隊開發微服務，而後經過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: oauth2
         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能力的快速開放。

關於API網關的詳情，能夠點擊下面連接進行體驗：https://console.huaweicloud.com/apig/?region=cn-north-1#/apig/expdemo