Swagger RESTful API文檔規範

*注意編寫的關鍵詞：「必須」、「不能」、「須要」、「應當」,「不得」、「應該」、「不該該」,「推薦」、「可能」和「可選的」

原文連接：http://swagger.io/specification/

介紹：

    swagger是一個用於描述項目和文檔RESTful api。

     這裏的規範定義了一組描述一個API所需的文件格式。 Swagger-UI項目所使用的這些文件能夠顯示API和Swagger-Codegen生成客戶在不一樣的語言。 額外的工具也能夠利用生成的文件,好比測試工具。

定義

路徑模板

路徑模板指的是使用大括號({ })URL路徑的部分標記爲可更換使用路徑參數。

Mime類型

Mime類型定義分佈在多個資源。 mime類型定義應符合RFC 6838。

一些例子可能的mime類型定義:

text/plain; charset=utf-8
  application/json
  application/vnd.github+json
  application/vnd.github.v3+json
  application/vnd.github.v3.raw+json
  application/vnd.github.v3.text+json
  application/vnd.github.v3.html+json
  application/vnd.github.v3.full+json
  application/vnd.github.v3.diff
  application/vnd.github.v3.patch

HTTP狀態代碼

HTTP狀態代碼是用來指示執行操做的狀態。 描述可用的狀態碼RFC 7231而在IANA狀態代碼註冊表。

規範

格式

描述RESTful API的文件按照大搖大擺規範表示爲JSON對象和符合JSON標準。 YAML是JSON的超集,也可使用 表明的規範文件。

例如,若是一個領域聽說數組值,將使用JSON數組表示:

{ "field" : [...] }

儘管使用JSON API描述它不強加一個JSON API自己輸入/輸出。

規範中的全部字段名稱區分大小寫的。

模式暴露了兩種類型的字段。 固定字段,聲明的名字,和有圖案的字段,字段名稱聲明一個正則表達式模式。 的字段能夠有屢次出現,只要每一個人都有一個唯一名稱。

文件結構

的狂妄表示API是由單個文件。 然而,部分的定義能夠分爲單獨的文件中,在用戶的自由裁量權。 這是適用於$ref字段的規範以下JSON模式定義。

按照慣例,大搖大擺規範文件命名swagger.json。

數據類型

原始數據類型大搖大擺規範中基於支持的類型JSON-Schema草案4。 模型是描述使用模式對象這是一個子集的JSON模式草案4。

一個額外的原始數據類型"file"使用參數對象和響應對象設置參數類型或響應做爲一個文件。

原語有一個可選的修飾符屬性format。 大搖大擺使用幾個已知的格式更精肯定義所使用的數據類型。 然而,format房地產是一個開放的string價值屬性,而且能夠支持文檔須要有任何價值。 格式如"email","uuid"等,可使用,即便他們不是由該規範定義的。 類型不伴隨着format屬性遵循它們的定義從JSON模式(除了file上面的類型定義)。 定義的格式的規範有:

普通的名字	type	format	說明
integer	integer	int32	簽署了32位
long	integer	int64	簽署了64位
float	number	float
double	number	double
string	string
byte	string	byte	base64編碼的字符
binary	string	binary	任何的八位字節序列
boolean	boolean
date	string	date	所定義的full-date- - - - - -RFC3339
dateTime	string	date-time	所定義的date-time- - - - - -RFC3339
password	string	password	用來提示用戶界面輸入須要模糊。

模式

這是一根文檔對象的API規範。 它結合了之前是什麼資源清單和API聲明(1.2和更早的版本)到一個文檔。

固定的字段

字段名	類型	描述
swagger	string	必需的。使用指定的規範版本。 能夠用它大搖大擺的UI和其餘客戶解釋API清單。 的值必須"2.0"。
info	Info Object	必需的。提供元數據API。 可使用元數據的客戶若是須要。
host	string	主機名或ip服務API。 這必定是主機,不包括計劃和sub-paths。 這可能包括一個港口。 若是host不包括,使用主機服務文檔(包括港口)。 的host不支持路徑模板。
basePath	string	API的基本路徑,這是相對的host。 若是不包括,API是直屬host。 必須從價值領先斜槓(/)。 的basePath不支持路徑模板。
schemes	[string]	API的傳輸協議。 值必須從列表中:"http","https","ws","wss"。 若是schemes不包括,默認使用計劃是用於訪問大搖大擺的定義自己。
consumes	[string]	一個MIME類型的api可使用列表。 這是能夠覆蓋全球全部API,但在特定的API調用。 值必須是所描述的Mime類型。
produces	[string]	MIME類型的api能夠產生的列表。 這是能夠覆蓋全球全部API,但在特定的API調用。 值必須是所描述的Mime類型。
paths	路徑對象	必需的。可用的路徑和操做的API。
definitions	定義對象	一個對象數據類型生產和使用操做。
parameters	參數定義對象	一個對象來保存參數,可使用在操做。 這個屬性不爲全部操做定義全局參數。
responses	反應定義對象	一個對象響應,能夠跨操做使用。 這個屬性不爲全部操做定義全球響應。
securityDefinitions	安全定義對象	安全方案定義規範,可使用。
security	(安全需求對象]	聲明的安全計劃申請API做爲一個總體。 值的列表描述替代安全方案,可使用(也就是說,有一個邏輯或安全需求之間)。 我的業務能夠覆蓋這個定義。
tags	(標籤對象]	的列表標籤使用的規範與額外的元數據。 標籤的順序能夠用來反思他們的訂單的解析工具。 並非全部使用的標籤操做對象必須聲明。 聲明的標籤不可能組織隨機或基於工具的邏輯。 列表中的每一個標記名稱必須是惟一的。
externalDocs	外部文檔對象	額外的外部文檔。

固定的字段

字段名	類型	描述
tags	(string]	的標籤列表API文檔控制。 標籤可用於邏輯分組業務的資源或任何其餘限定符。
summary	string	什麼操做的一個簡短的總結。 最大swagger-ui可讀性,這一領域應小於120個字符。
description	string	詳細解釋操做的行爲。GFM語法可用於富文本表示。
externalDocs	外部文檔對象	額外的外部文檔操做。
operationId	string	獨特的字符串用於識別操做。 id必須是惟一的在全部業務中所描述的API。 工具和庫可使用operationId來惟一地標識一個操做,所以,建議遵循通用的編程的命名約定。
consumes	[string]	MIME類型的列表操做可使用。 這將覆蓋consumes定義在炫耀的對象。 空值可用於全球定義清楚。 值必須是所描述的Mime類型。
produces	[string]	MIME類型的列表操做能夠產生。 這將覆蓋produces定義在炫耀的對象。 空值可用於全球定義清楚。 值必須是所描述的Mime類型。
parameters	(參數對象 |引用對象]	適用於該操做的參數列表。 若是已經定義了一個參數道路項目新定義將覆蓋它,但不能刪除它。 必須不包含重複的參數列表。 一個獨特的參數定義的組合的名字和位置。 可使用列表引用對象連接到參數的定義的對象的參數。 能夠有一個「身體」參數。
responses	響應對象	必需的。返回的列表可能的反應,由於他們執行這個操做。
schemes	[string]	傳輸協議的操做。 值必須從列表中:"http","https","ws","wss"。 的值將覆蓋的對象schemes定義。
deprecated	boolean	聲明該操做被棄用。 使用聲明的操做應該沒有。 默認值是false。
security	(安全需求對象]	聲明的安全計劃申請這個操做。 值的列表描述替代安全方案,可使用(也就是說,有一個邏輯或安全需求之間)。 這個定義覆蓋任何宣佈頂級security。 刪除一個頂級安全聲明,可使用一個空數組。