為什么要實(shí)現(xiàn)API文檔化亲雪？
API文檔化有利于前后端分離的開展里初。隨著開發(fā)方式全面轉(zhuǎn)成前后端分離，前端和后端的唯一溝通就在API層面煌茴。在沒有文檔化之前随闺，開發(fā)人員只能口頭的交代并反復(fù)理解每個(gè)接口參數(shù)和返回值，這個(gè)過程相當(dāng)不穩(wěn)定蔓腐，變化頻繁矩乐。而通過API文檔化后，可以通過文檔的清晰定義回论，使得前后端人員減少無畏溝通散罕，并在理解上保持一致；
API文檔化有利于接口自動(dòng)化測試傀蓉。公司馬上上馬接口自動(dòng)化測試欧漱，對接口參數(shù)和返回值要通過Json方式導(dǎo)入自動(dòng)化測試程序。而用特殊工具生成的API文檔僚害，可以直接輸出json格式的文檔硫椰，簡化了測試流程，減輕了開發(fā)人員的工作量萨蚕；
API文檔化有利于系統(tǒng)文檔建設(shè)靶草。開發(fā)人員不愿意寫文檔，寫注釋岳遥。而為了以上兩個(gè)目的必須要求開發(fā)人員在編碼的同時(shí)補(bǔ)充相關(guān)的API描述奕翔，而通過一個(gè)相對穩(wěn)定成熟和趁手的工具可以大大減輕文檔的工作量，做到事半功倍浩蓉。
Swagger和spring-boot-starter-swagger
Swagger是業(yè)界比較流行的實(shí)現(xiàn)API文檔化的工具派继。優(yōu)點(diǎn)有
- 通過在項(xiàng)目中引入Swagger，可以使用簡單的Annotation捻艳，就實(shí)現(xiàn)了API文檔化驾窟；
- Swagger提供標(biāo)準(zhǔn)的json或yaml文檔，方便做進(jìn)一步解析认轨，典型應(yīng)用是接口自動(dòng)化測試绅络；
- 頁面可以直接進(jìn)行測試（try-it-out功能，部分替代Postman）嘁字；
- Swagger還提供類似于github的SwaggerHub恩急，相當(dāng)于公共的API文檔集散地。
Swagger的項(xiàng)目主頁：https://swagger.io/
為了將Swagger和公司現(xiàn)有技術(shù)框架相結(jié)合纪蜒，在網(wǎng)上發(fā)現(xiàn)了這么一個(gè)小項(xiàng)目spring-boot-starter-swagger衷恭，將公司項(xiàng)目和Swagger的集成又簡化了一步，特此向作者表示感謝纯续。
作者在簡書上的介紹文章：http://www.reibang.com/p/91c5a8565a45
主要優(yōu)點(diǎn)：
- 引入足夠簡單随珠，只需要2步（如果有Shiro就是3步）
- 方便的Swagger開關(guān)
- 支持yaml格式的配置
- 支持API的分組顯示（在API過多的情況下非常好用）
- 支持JSR-303校驗(yàn)注解（@Min, @Max, @Pattern等）
- 依然在維護(hù)完善灭袁，逐步增加更多配置和開關(guān)
Swagger引入方法
- pom文件引入
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>spring-boot-starter-swagger</artifactId>
<version>1.5.1.RELEASE</version>
</dependency>
- 主文件加Annotation
@SpringBootApplication
@EnableSwagger2Doc
public calss TestSwaggerApplication{
- 增加Shiro的anon設(shè)置（防止被登錄轉(zhuǎn)向）
client:
filters:
filter:
chain:
definitions: /swagger-ui.html=anon;/webjars/**=anon;/swagger-resources/**=anon;/v2/api-docs/**=anon;/**=authc;
- 配置文件
配置文件統(tǒng)一放到了項(xiàng)目的application.yml中，稍后計(jì)劃使用新的文件牙丽，并采用引入的方式實(shí)現(xiàn)配置文件的分離
4.1 公共信息
定義整個(gè)項(xiàng)目的總體信息简卧。
swagger:
# 公共信息
enabled: true
title: swagger-demo
description: 一個(gè)Swagger測試項(xiàng)目
version: 0.1-SNAPSHOT
# 許可證及服務(wù)條款信息
license:
licenseUrl:
termsOfServiceUrl:
contact:
name: Carisma
url:
email: carisma.zhao@gmail.com
base-package: me.learning.swagger
4.2 分組策略
分組策略指的是在整個(gè)項(xiàng)目中，將不同類型的API接口分散到不同的頁面烤芦，方便查看和測試。
# 分組策略
docket:
apiForMe:
title: Myself
description: 開放給自己的接口
base-path: /api/myself/**
apiForOthers:
title: Others
description: 作為其他人的接口
base-path: /api/others/**
4.3 公共參數(shù)和通用錯(cuò)誤碼
像每個(gè)接口都需要鑒權(quán)這種參數(shù)析校，可以在配置文件中統(tǒng)一定義构罗，這樣省去每個(gè)接口再寫的麻煩，也能兼顧頁面的測試智玻。
# 公共參數(shù)
global-operation-parameters[0]:
name: TOKEN
description: 鑒權(quán)
modelRef: string
parameterType: header
# 公共參數(shù)寫成requierd, 對于不需要登錄的接口隨便寫一個(gè)字符串即可
required: true
# 通用返回錯(cuò)誤碼
apply-default-response-messages: true
global-response-message.get[0]:
code: 401
message: 401錯(cuò)誤
global-response-message.get[1]:
code: 500
message: 后端錯(cuò)誤
modelRef: ERROR
Swagger的效果查看
以上配置完成后遂唧，Swagger直接可以生成文檔，而不需要單獨(dú)在每個(gè)需要顯示的API上添加Annotation吊奢，當(dāng)然下面會(huì)講到如果需要更清晰的顯示盖彭，還要使用注解，使用注解后页滚，查看方式依然是以下兩種召边。
- API文檔：在瀏覽器中輸入
localhost:9120/swagger-ui.html即可。端口號(hào)為Application的啟動(dòng)端口裹驰； - Json文件：如果沒有分組隧熙，則直接使用
localhost:9120/swagger-ui.html/v2/api-doc，即顯示API的Json格式（包括對model的解析）幻林，如果使用了分組贞盯，則需要每個(gè)分組單獨(dú)顯示，例如localhost:9120/swagger-ui.html/v2/api-doc/?group=apiForMe
Annotation使用詳解
要想詳細(xì)的沪饺、切合實(shí)際的展示API的內(nèi)容與要求躏敢，則必須在API和Model上加單獨(dú)的注解，官方JavaDoc雖然不是很詳細(xì)整葡，但是作為參考也夠了（剩下的就是自己試了）：
http://docs.swagger.io/swagger-core/current/apidocs/index.html?io/swagger/annotations/Api.html
其中常用的有以下幾個(gè)件余，親測后有些需要詳細(xì)說明：
@Api
加在需要自定義注解的API類（*Controller）上。這個(gè)注解沒有什么屬性需要說的掘宪，其中value比較奇葩蛾扇，官方說法是隱含的代替tag的作用。（那就用tag不就完了魏滚？）為了清晰化接口镀首，使用方式應(yīng)該是分組>tag>value，即首先用分組分隔鼠次，然后使用tag屬性更哄，value屬性最好就不再使用了芋齿。
@ApiOperation
加在API的每個(gè)路徑映射方法上（即真正的API接口）。value屬性是必須的成翩，描述該接口的內(nèi)容觅捆，可以是中文。
response和responseContainer是兩個(gè)重要的屬性麻敌。前者表示返回的類栅炒，典型的Model.class，注意不是字符串术羔，IDEA是可以解析的（Swagger體系內(nèi)自動(dòng)的做成一種Reference）赢赊；后者可選值為："List"，"Set"或者"Map"级历，注意是字符串释移。
@ApiImplicitParam & @ApiImplicitParams
加在API的參數(shù)上，最重要的注解之一寥殖。另有一個(gè)@ApiParam玩讳，是加在函數(shù)簽名里面，不推薦嚼贡，這兩個(gè)是在函數(shù)簽名的外面熏纯，更清晰。后者是前者的集合编曼，比較簡單豆巨，就不贅述了。前者比較重要的屬性有
- name：和參數(shù)變量名保持一致掐场；
- value：對這個(gè)參數(shù)的簡要描述往扔；
- required：是否必須；
- dataType：數(shù)據(jù)類型熊户，注意原生類型（包裝類也用原生的表示萍膛，例如Integer寫"int"）都是小寫，包括"string"嚷堡；
- paramType：參數(shù)類型蝗罗，"body"是普通參數(shù)，"path"是路徑上的那種參數(shù)蝌戒，"query"是url中問號(hào)的那種參數(shù)串塑；
- allowableValues：參數(shù)允許的值，這個(gè)屬性對自動(dòng)化測試比較重要北苟，具體參考JavaDoc桩匪，實(shí)際使用中最好寫明。需要說明的是友鼻，在paramType為body時(shí)傻昙，range的設(shè)置是不生效的（原因未知）闺骚。
@ApiModel
以下兩個(gè)注解都是加在Model里，便于在文檔中對自定義類做詳細(xì)的說明妆档。這個(gè)注解加在Model類上僻爽。value屬性可以提供一個(gè)名字，在文檔中贾惦，會(huì)替換原來model的類名（沒有試中文是否可行）胸梆。同時(shí)提供對超類和子類的描述，非字符串须板，便于生成繼承關(guān)系（感覺這個(gè)功能可以通過代碼分析實(shí)現(xiàn)）
@ApiModelProperty
加在Model的屬性上乳绕，對屬性做進(jìn)一步描述和限定。同時(shí)這個(gè)注解可以加在getXXX方法上逼纸，如果XXX屬性上也有，則以屬性上的注解描述為準(zhǔn)济蝉〗芄簦考慮提供方法上加注解，可能是方便描述超類中的這個(gè)字段吧（protected類型）王滤。該注解使用方式和@ApiImplicitParam類似贺嫂。
由于引入了spring-boot-starter-swagger，可以直接支持JSR-303校驗(yàn)類的注解雁乡，包括@Pattern第喳、@Max、@Min踱稍、@Size等曲饱。感覺Pattern是無法用@ApiModelProperty的屬性替代的，其他好像都可以珠月，說的不對還請作者指正扩淀。
