1、Swagger是什么
? 是一款讓你更好的書寫API文檔的規(guī)范且完整的框架
? 提供描述、生產(chǎn)诊笤、消費和可視化RESTful Web Service
? 是由龐大的工具集合支撐的形式化規(guī)范嫡锌，這個集合涵蓋了從終端用戶接口、底層代碼庫到商業(yè)API管理的方方面面
2檬寂、常用注解
? （1） @Api 用在類上终抽，說明該類的作用，可以標記一個controller類作為swagger文檔資源桶至，使用方式：
? ? ? ????? @Api(value = "/user", description = "Operations about user")
??????????? 常用參數(shù)：
? ? ? ??????????????????? tags："說明該類的作用昼伴，非空時將覆蓋value的值"
? ? ? ? ? ? ? ? ? ? ? ? ? value："描述類的作用"
? ? ? ? ? ? ? ??????????? description：對api資源的描述，在1.5版本后不再支持
? ? ? ? ? ? ? ??????????? basePath：基本路徑可以不配置镣屹，在1.5版本后不再支持
? ? ? ? ? ? ? ??????????? position：如果配置多個Api 想改變顯示的順序位置圃郊，在1.5版本后不再支持
????????????????????????? produces：設(shè)置MIME類型列表（output），例："application/json, application/xml"女蜈，默認為空
????????????????????????? consumes：設(shè)置MIME類型列表（input）持舆，例："application/json, application/xml"，默認為空
????????????????????????? protocols：設(shè)置特定協(xié)議伪窖，例：http， https竹伸， ws佩伤， wss。
????????????????????????? authorizations：獲取授權(quán)列表（安全聲明）生巡，如果未設(shè)置孤荣，則返回一個空的授權(quán)值钱豁。
????????????????????????? hidden：默認為false牲尺， 配置為true 將在文檔中隱藏復(fù)制代碼? ? ?
? （2） @ApiOperation 用在方法上谤碳，說明方法的作用蜒简，每一個url資源的定義，使用方式：
? ? ? ????? @ApiOperation(value = "Find purchase order by ID",
? ? ? ? ?????????????????????????????? notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
? ? ? ? ?????????????????????????????? response = Order,tags = {"Pet Store"})
??????????? 常用參數(shù)：
? ? ? ??????????????????? value："說明方法的用途卷仑、作用"
? ? ? ? ? ? ? ??????????? notes："方法的備注說明"
? ? ? ? ? ? ? ? ? ? ? ? ? tags：操作標簽系枪，非空時將覆蓋value的值
? ? ? ? ? ? ? ? ? ? ? ? ? response：響應(yīng)類型（即返回對象）
? ? ? ? ? ? ? ??????????? responseContainer：聲明包裝的響應(yīng)容器（返回對象類型）。有效值為 "List", "Set" or "Map"衬浑。
????????????????????????? responseReference：指定對響應(yīng)類型的引用工秩。將覆蓋任何指定的response（）類
????????????????????????? httpMethod：指定HTTP方法助币，"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
????????????????????????? position：如果配置多個Api 想改變顯示的順序位置，在1.5版本后不再支持
????????????????????????? nickname：第三方工具唯一標識俭缓，默認為空
????????????????????????? produces：設(shè)置MIME類型列表（output）愿吹，例："application/json, application/xml"犁跪，默認為空
???????????????????????? consumes：設(shè)置MIME類型列表（input），例："application/json, application/xml"，默認為空
???????????????????????? protocols：設(shè)置特定協(xié)議逞刷，例：http， https帆喇， ws， wss婉刀。
???????????????????????? authorizations：獲取授權(quán)列表（安全聲明），如果未設(shè)置律秃，則返回一個空的授權(quán)值。
???????????????????????? hidden：默認為false迁客， 配置為true 將在文檔中隱藏
???????????????????????? responseHeaders：響應(yīng)頭列表
???????????????????????? code：響應(yīng)的HTTP狀態(tài)代碼粘室。默認 200
???????????????????????? extensions：擴展屬性列表數(shù)組
? （3） @ApiParam 請求屬性，使用方式：
? ? ? ??????? public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true)? User user)
? ? ? ????? 常用參數(shù)：
? ? ? ??????????????????? name：參數(shù)名稱海雪，參數(shù)名稱可以覆蓋方法參數(shù)名稱锦爵，路徑參數(shù)必須與方法參數(shù)一致
? ? ? ? ? ? ? ??????????? value：參數(shù)的簡要說明险掀。
? ? ? ? ? ? ? ??????????? defaultValue：參數(shù)默認值
? ? ? ? ? ? ? ??????????? required:屬性是否必填，默認為false [路徑參數(shù)必須填]
其他參數(shù)：
? ? ? ? ? ? ? ? ? ? ? ? ? allowableValues:限制參數(shù)的可接受值。1.以逗號分隔的列表? 2、范圍值? 3、設(shè)置最小值/最大值
? ? ? ? ? ? ? ??????????? access:允許從API文檔中過濾參數(shù)。
? ? ? ? ? ? ? ??????????? allowMultiple:指定參數(shù)是否可以通過具有多個事件接受多個值，默認為false
? ? ? ? ? ? ? ???????????? hidden:隱藏參數(shù)列表中的參數(shù)。
? ? ? ? ? ? ? ???????????? example:單個示例
? ? ? ? ? ? ? ???????????? examples:參數(shù)示例。僅適用于BodyParameters
? （4） @ApiResponse 響應(yīng)配置市咽，用在 @ApiResponses 中痊银，一般用于表達一個錯誤的響應(yīng)信,使用方式：
? ? ? ????? @ApiResponse(code = 400, message = "Invalid user supplied")
? （5） @ApiResponses 響應(yīng)集配置，用在請求的方法上，表示一組響應(yīng),使用方式：
? ? ? ????? @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
??????????? 常用參數(shù)：
? ? ? ???????????????????? code：數(shù)字致稀，例如400
? ? ? ? ? ? ? ???????????? message：信息冈闭，例如"請求參數(shù)沒填好"
? ? ? ? ? ? ? ? ? ? ? ? ?? response：拋出異常的類
? （6） @ResponseHeader 響應(yīng)頭設(shè)置，使用方式：
? ? ? ????? @ResponseHeader(name="head1",description="response head conf")
? （7） @ApiIgnore 用于類或方法上抖单，可以不被swagger顯示在頁面上
? （8） @ApiModel 用在請求的類上萎攒，表示對類的說明；用于響應(yīng)類上矛绘，表示返回一個響應(yīng)數(shù)據(jù)的信息（這種一般用在post創(chuàng)建的時候耍休，使用 @RequestBody這樣的場景，請求參數(shù)無法使用 @ApiImplicitParam注解進行描述的時候）
? ? ? ? ? ? @ApiModelProperty：用在屬性上货矮，描述響應(yīng)類的屬性
? ? ? ? 使用方式：
? ? ? ??????????????? @ApiModel(value="用戶登錄信息", description="用于判斷用戶是否存在")
? ? ? ? ? ? ? ? ? ? ? public class UserModel implements Serializable{
? ? ? ? ? ? ? ? ? ???????????? private static final long serialVersionUID = 1L;
? ? ? ? ? ? ? ? ? ? ? ? ? ? ?? /**用戶名 */
? ???????????????????????????? @ApiModelProperty(value="用戶名")
? ????????????????????????????? private String account;
? ????????????????????????????? /**密碼 */
? ????????????????????????????? @ApiModelProperty(value="密碼")
? ?????????????????????????????? private String password;
}
? ? ? ? 常用參數(shù)：
? ? ? ???????????????? value:此屬性的簡要說明
? ? ? ? ? ? ? ???????? name:允許覆蓋屬性名稱
??????? 其他參數(shù):
? ? ? ???????????????? allowableValues:限制參數(shù)的可接受值羊精。1.以逗號分隔的列表? 2、范圍值? 3囚玫、設(shè)置最小值/最大值
? ? ? ? ? ? ? ? ? ? ?? access:允許從API文檔中過濾屬性园匹。
? ? ? ? ? ? ? ???????? notes:目前尚未使用。
? ? ? ? ? ? ? ???????? dataType:參數(shù)的數(shù)據(jù)類型劫灶。可以是類名或者參數(shù)名掖桦，會覆蓋類的屬性名稱本昏。
? ? ? ? ? ? ? ???????? required:參數(shù)是否必傳，默認為false
? ? ? ? ? ? ? ???????? position:允許在類中對屬性進行排序枪汪。默認為0
? ? ? ? ? ? ? ???????? hidden:允許在Swagger模型定義中隱藏該屬性涌穆。
? ? ? ? ? ? ? ???????? example:屬性的示例。
? ? ? ? ? ? ? ???????? readOnly:將屬性設(shè)定為只讀雀久。
? ? ? ? ? ? ? ???????? reference:指定對相應(yīng)類型定義的引用宿稀，覆蓋指定的任何參數(shù)值
? （9） @ApiImplicitParams 用在請求的方法上，表示一組參數(shù)說明
? ? ? ???? @ApiImplicitParam:用在 @ApiImplicitParams注解中赖捌，指定一個請求參數(shù)的各個方面
使用方式：
? ? ? ? @ResponseBody
??????? @PostMapping(value="/login")
??????? @ApiOperation(value = "登錄檢測", notes="根據(jù)用戶名祝沸、密碼判斷該用戶是否存在")
??????? @ApiImplicitParams({
? ? ??? @ApiImplicitParam(name = "name", value = "用戶名", required = false, paramType = "query", dataType = "String"),
? ? ??? @ApiImplicitParam(name = "pass", value = "密碼", required = false, paramType = "query", dataType = "String")
})
public UserModel login(@RequestParam(value = "name", required = false) String account,
@RequestParam(value = "pass", required = false) String password){}
常用參數(shù)：
? ? ? ???????? name：參數(shù)名，參數(shù)名稱可以覆蓋方法參數(shù)名稱越庇，路徑參數(shù)必須與方法參數(shù)一致
?????????????? value：參數(shù)的漢字說明罩锐、解釋
?????????????? required：參數(shù)是否必須傳，默認為false [路徑參數(shù)必填]
?????????????? paramType：參數(shù)放在哪個地方
? ???????????? ·header --> 請求參數(shù)的獲嚷卑Α：@RequestHeader
? ???????????? ·query --> 請求參數(shù)的獲壬蟆：@RequestParam
? ???????????? ·path（用于restful接口）--> 請求參數(shù)的獲取：@PathVariable
? ???????????? ·body（不常用）
? ? ? ? ? ? ?? ·form（不常用）
?????????????? dataType：參數(shù)類型桑驱，默認String竭恬，其它值dataType="Integer"
?????????????? defaultValue：參數(shù)的默認值
? 其他參數(shù)：
? ? ? ? ? ? ? ? allowableValues：限制參數(shù)的可接受值跛蛋。1.以逗號分隔的列表? 2、范圍值? 3痊硕、設(shè)置最小值/最大值
??????????????? access：允許從API文檔中過濾參數(shù)赊级。
??????????????? allowMultiple：指定參數(shù)是否可以通過具有多個事件接受多個值，默認為false
??????????????? example：單個示例
??????????????? examples：參數(shù)示例寿桨。僅適用于BodyParameters
3此衅、Swagger的優(yōu)勢
a:支持API自動生成同步的在線文檔：使用swagger后可以直接通過代碼生成文檔，不再需要自己手動編寫接口文檔亭螟，對程序員來說非常方便挡鞍，可以節(jié)約寫文檔的時間去學(xué)習(xí)新的技術(shù)
b:提供web頁面的在線測試API：光有文檔還不夠，Swagger生成的文檔预烙，還支持在線測試墨微。參數(shù)和格式都定好了，直接在界面上輸入?yún)?shù)對應(yīng)的值即可在線測試接口
4扁掸、Swagger的目標
swagger的目標是對REST API定義一個標準的且和語言無關(guān)的接口翘县，可以讓人和計算機擁有無需訪問源碼、文檔或網(wǎng)絡(luò)流量監(jiān)測就可以發(fā)現(xiàn)和理解服務(wù)的能力谴分，當通過swagger進行正確定義锈麸，用戶可以理解遠程服務(wù)并使用最少實現(xiàn)邏輯與遠程服務(wù)進行交互。與底層接口所實現(xiàn)的接口類似牺蹄，Swagger消除了調(diào)用服務(wù)時可能會有的猜測忘伞。
