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。 刪除一個頂級安全聲明,可以使用一個空數組。