OpenAPI 是什麼?
Open API 即開放 API，也稱開放平臺。 所謂的開放 API（OpenAPI）是服務型網站常見的一種應用，網站的服務商將自己的網站服務封裝成一系列
API（Application Programming Interface，應用編程接口）開放出去，供第三方開發者使用，這種行爲就叫做開放網站的 API，所開放的 API 就被稱作 OpenAPI（開放 API ）。
RESTful API 是什麼?
什麼是 REST？
Representational State Transfer，翻譯是”表現層狀態轉化”。可以總結爲一句話：REST 是所有 Web 應用都應該遵守的架構設計指導原則。
面向資源是 REST 最明顯的特徵，對於同一個資源的一組不同的操作。資源是服務器上一個可命名的抽象概念，資源是以名詞爲核心來組織的，首先關注的是名詞。REST 要求，必須通過統一的接口來對資源執行各種操作。對於每個資源只能執行一組有限的操作。
什麼是 RESTful API？
符合 REST 設計標準的 API，即 RESTful API。REST 架構設計，遵循的各項標準和準則，就是 HTTP 協議的表現，換句話說，HTTP 協議就是屬於 REST 架構的設計模式。比如，無狀態，請求-響應。。。
Swagger 是什麼?
Swagger™ 的目標是爲 REST APIs 定義一個標準的，與語言無關的接口，使人和計算機在看不到源碼或者看不到文檔或者不能通過網絡流量檢測的情況下能發現和理解各種服務的功能。當服務通過 Swagger 定義，消費者就能與遠程的服務互動通過少量的實現邏輯。類似於低級編程接口，Swagger 去掉了調用服務時的很多猜測。
舉個例子：
現在的互聯網充滿了一個又一個信息孤島和大量的碎片化的數據，用戶想知道一些資訊，必須在不同的網站上跑來跑去.比如看電影，首先去google map查看周圍的電影院，然後去大衆點評網查看對這家電影院的評論，然後去電影院的網站上看看今天有什麼電影上映。然後支付網站進行電子購票.整個過程非常繁瑣，數據之間沒有關聯.充斥着大量的異構系統.
爲了解決這些問題.我們引入了openapi的概念.通過openapi,數據提供商開放了自己的數據，通過mashup將信息孤島連接起來.整合這些信息碎片.
如果google,大衆點評網，電影院，支付寶均開放自己的openapi.然後有一個mashup程序將他們整合起來.那麼用戶就能體驗一站式購物.進這個網站，找到電影院，查看電影院評價，如果評價好，查看電影院上映什麼節目。電子訂票.然後就能直接殺過去了。省時省力 。
四類api ：
同步服務api: 普通的Http無狀態單次請求和響應
異步服務api: 應用於服務提供商提供的服務無法在當時處理完畢，先返回一個請求響應，當服務處理結束以後再將服務處理結果返回給服務調用者
訂閱服務api: 類似rss.服務調用者只需要訂閱服務即可獲得服務提供商推送的服務內容
大數據量上傳api: 上傳文件
什麼是oauth?
OAuth協議致力於使網站和應用程序（統稱爲消費方）能夠在無須用戶透露其認證證書的情況下，通過API訪問某個web服務（統稱爲服務提供方）的受保護資源。更一般地說，OAuth爲API認證提供了一個可自由實現且通用的方法。
什麼是openid?
OpenID 是一個以用戶爲中心的數字身份識別框架，它具有開放、分散、自由等特點
什麼是Mashup?
mashup是糅合，是當今網絡上新出現的一種網絡現象,將兩種以上使用公共或者私有數據庫的web應用，加在一起，形成一個整合應用。一般使用源應用的api接口，或者是一些rss輸出（含atom）作爲內容源，合併的web應用用什麼技術，則沒有什麼限制。
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對象聲明瞭用於文檔的規範的版本。該版本對於用戶理解文檔的結構至關重要，更重要的是，對於可能爲了驗證目的而獲取文檔或創建虛擬服務的任何工具，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有在線編輯器可以體驗。