swagger-ui
采用Vue+element-ui構(gòu)建的swagger-ui，Github地址：
https://github.com/yaojunguang/swagger-ui
介紹
在日常開發(fā)中，接口文檔維護(hù)一直是項(xiàng)目管理中的頭疼的問題，還有就是單元測試、接口測試等。swagger是我極具推崇的開發(fā)輔助工具，很好的解決了上訴的這些問題
在移動(dòng)端開發(fā)過程中module生成也一直是費(fèi)力而麻煩的事情(java對android可公共module包解決)，以前也做過一個(gè)用java class反射生成 swift module的小工具
以前一直在使用springfox-swagger-ui作為swagger的ui展示，但是在實(shí)際使用過程中有諸多的不滿意的地方，遂結(jié)合自己的實(shí)際需求，采用Vue+element-ui自行開發(fā)了這個(gè)項(xiàng)目
主要的功能特色如下：
0、概覽
1、采用左右布局，便于充分利用屏幕空間
2、左側(cè)方案按tag分組，便于集中管理
3、左側(cè)導(dǎo)航欄支持寬度調(diào)整，調(diào)整結(jié)果保存到cookie
4、右側(cè)項(xiàng)目部分tab化管理，便于打開多個(gè)
5、參數(shù)可分組，默認(rèn)以描述中以"【公共參數(shù)】"開頭的放入到公共參數(shù)中（具體原因后續(xù)有機(jī)會(huì)在介紹），該函數(shù)獨(dú)有參數(shù)放入專有參數(shù)并默認(rèn)展開
6、返回實(shí)體結(jié)果全部列舉，支持一鍵轉(zhuǎn)化為swift和java，module代碼格式化高亮處理，一鍵復(fù)制
7、在線直接調(diào)用測試
8、運(yùn)行結(jié)果格式化高亮展示
約定
該swagger是根據(jù)我在日常開發(fā)中的一些個(gè)人需求自行定制的swagger-ui,其中涉及到諸多約定
1、返回結(jié)果為JSON
2、不根據(jù)http的狀態(tài)碼判斷內(nèi)部邏輯處理是否正確，而是通過外包一個(gè)包裝類來返回結(jié)果
3、返回結(jié)果需要指明類型，這樣swagger才能識別，如下面的例子
@ResponseBody
@ApiOperation(value = "喜歡的列表", notes = "喜歡-列表")
@RequestMapping(value = "", method = RequestMethod.GET)
public RespEntity<List<LovesCellEntity>> findByPage(
? ? ? ? @ApiParam(value = "頁碼")
? ? ? ? @RequestParam(name = "page") int page,
? ? ? ? @ApiParam(value = "類型，0酒單，1文章，2視頻")
? ? ? ? @RequestParam(name = "itemType") int itemType,
? ? ? ? BaseReq req) {
? ? RespEntity<List<LovesCellEntity>> respEntity = RespEntity.One(req);
? ? try {
? ? ? ? .....
? ? } catch (Exception ex) {
? ? ? ? error(ex, respEntity);
? ? }
? ? return respEntity;
}
4、為了便于維護(hù)管理接口分組，Controller的tag都已數(shù)字開頭，便于自動(dòng)排序，如下：
@RestController
@Api(tags = {"05、喜歡"})
@RequestMapping(value = "/v8/love")
public class LoveControllerV8 extends BaseControllerV8 {
? .....
}
5、該項(xiàng)目建立的目的是為了方便交流維護(hù)(要有注釋)，所涉及的實(shí)體對象均需要按照swagger注解要求填寫如下返回實(shí)體
對于@ApiModel的注解，不要使用value屬性，否者會(huì)使類名不一直
@Data
@ApiModel(description = "CartUiEntity")
public class CartUiEntity {
? ? @ApiModelProperty("地址編號")
? ? private int addressId = 0;
? ? @ApiModelProperty("收件人")
? ? private String recipient;
? ? @ApiModelProperty("電話號碼")
? ? private String mobile;
? ? @ApiModelProperty("詳細(xì)地址")
? ? private String addressDetail;
}
測試運(yùn)行
測試運(yùn)行中項(xiàng)目中包含了一個(gè)swagger文檔sample文件，可自行替換（src/assets/api-docs.json）
# 依賴安裝
npm install
# 測試運(yùn)行
npm run dev
# 生產(chǎn)打包
npm run build:prod
打包為JAR
打包過程默認(rèn)為npm run build:prod.會(huì)自動(dòng)切換為包所在的本地環(huán)境
# mvn生產(chǎn)打包發(fā)布
mvn install
安裝
前置
安裝好swagger2，并按默認(rèn)配置，不需要其他第三方的swagger-ui，只需要加入默認(rèn)依賴
<dependency>
? ? <groupId>io.springfox</groupId>
? ? <artifactId>springfox-swagger2</artifactId>
? ? <version>${swagger.version}</version>
</dependency>
jar復(fù)制安裝
復(fù)制生成的swagger-ui-0.4.jar 到你的工程下，添加依賴即可
<dependency>
? ? <groupId>com.smarthito</groupId>
? ? <artifactId>swagger-ui</artifactId>
? ? <version>0.4</version>
? ? <scope>system</scope>
? ? <systemPath>${pom.basedir}/src/main/libs/swagger-ui-0.4.jar</systemPath>
</dependency>
maven依賴
<dependency>
? ? <groupId>com.smarthito</groupId>
? ? <artifactId>swagger-ui</artifactId>
? ? <version>0.4</version>
</dependency>
訪問
默認(rèn)頁面 /swagger-ui.html
http://<host>:<port>/swagger-ui.html
TODO:
支持一鍵生成移動(dòng)端調(diào)用代碼
作為公開庫，不同公司的調(diào)用模塊不盡相同，大家可根據(jù)實(shí)際需求修改
支持枚舉對象的導(dǎo)出
實(shí)際開發(fā)中，狀態(tài)變量的枚舉一直是前后端溝通的問題，這個(gè)部分的導(dǎo)出需要一些開發(fā)約定，在未想好對開發(fā)過程無干擾的情況下暫時(shí)擱置（java 采用class反射可實(shí)現(xiàn)，但對開源項(xiàng)目安全性角度不想采用）。
后語：
該項(xiàng)目對于采用swagger注釋完善度要求極高，這樣可以使整個(gè)工具呈現(xiàn)完美狀態(tài)，這個(gè)部分也有一些其它的自定義小工具，后續(xù)會(huì)再分享，如：數(shù)據(jù)庫表生成module的groovy schema等
