自制的springboot接口文檔組件swagger2

簡介

什麼是 swagger?

**Swagger 是一款自動生成在線文檔 + 接口調試的工具。在 WEB 開發中不可否認的是我們需要給客戶端提供 API 接口，這個時候需要藉助 postman、rap 等工具
進行調試，以便於接口能正常交付給客戶端人員，用過其它工具的應該知道一個 POST 請求一堆參數是非常枯燥且煩人的事情，而 swagger 就是讓你擺脫這種束縛感….**

源碼地址

• GitHub：https://github.com/battcn/swagger-spring-boot
• 碼雲：https://gitee.com/battcn/spring-boot-starter-swagger/

swagger-spring-boot-starter 是一款建立在swagger基礎之上的工具包，利用SpringBoot自動裝配的特性，簡化了傳統swagger的繁瑣配置

項目介紹

• swagger-vue ：採用 Vue 編寫的源代碼，如果您對UI有更好的想法或者建議可以在該項目上進行擴展，它就是 UI 的源文件
• swagger-vue-ui ：編譯後的純 HTML 文件，如果你對 swagger-spring-boot-starter 包中的 UI 感到不滿，你也可以選擇排除 swagger-vue-ui 然後用第三方的…
• swagger-spring-boot-starter ： 自動裝配 swagger 的擴展包

有興趣擴展自己的Starter包的可以參考文章：編寫自己的starter項目

如果該項目對您有幫助，歡迎Fork和Star，有疑問可以加 QQ：1837307557一起交流 ，如發現項目BUG可以提交Issue

使用

1.X 版本需要在啓動類添加 @EnableSwagger2Doc 但是 2.X 版本後無需添加，請知曉…

• 在pom.xml中引入依賴：

<dependency>
    <groupId>com.battcn</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>2.0.6-RELEASE</version>
</dependency>

• 在application.yml中添加

spring:
  swagger:
    enable: true

• 在application.properties中添加

spring.swagger.enable=true

更新記錄

2.0.6
  發佈時間：2018-07-25
  更新內容：
    1.解決請求錯誤時，異常信息不渲染的BUG
    2.優化登陸保存策略
2.0.5
  發佈時間：2018-07-24
  更新內容：
    1.修復 spring.swagger.host 導致調試面板失效BUG
2.0.4
  發佈時間：2018-07-23
  更新內容：
    1.修改未自動注入BUG（在2.0.3中需要寫明 ComponentScan）
2.0.2（具體效果看 samples-basic 中的項目示例）
2.0.3
  發佈時間：2018-07-17
  更新內容：
    1.UI美化
    2.路由優化
    3.文件上傳控件美化
2.0.2（具體效果看 samples-basic 中的項目示例）
  發佈時間：2018年07月10日
  更新內容：
    1.UI添加響應結果
    2.UI添加全局認證窗口
    3.修復接口過多導致內存溢出泄露BUG
    4.優化代碼風格與標準
    5.美化彈窗
    6.添加安全驗證過濾器（這樣一來即使你想線上使用 swagger 一樣可以）
    7.登陸UI，保障接口安全
    8.添加請求響應時間
    9.升級Spring Boot 版本爲 2.0.3-RELEASE
2.0.1
  發佈時間：2018年06月19日
  更新內容：
    1.重寫UI
    2.升級Spring Boot 爲2.0.2
    3.支持接口全局認證（設置一次 Token 需驗證的地址自動將值寫入到請求頭/請求體中）
    4.全局響應返回
    5.支持可選的 Bean 驗證插件；
        由於日常開發中發現默認啓動的驗證插件掃描耗時比較久（由於我電腦弱，掃描時間大概在3-5秒...）
        故而將插件修改爲可選的，默認是關閉
    6.支持選項卡切換
    7.修復多餘的斜槓
1.4.5
  發佈時間：2018年04月26日
  更新內容：
    1.解決配置 `context-path` 導致 `swagger-ui.html` 無法顯示BUG
1.4.4
  發佈時間：2018年01月05日
  更新內容：
    1.優化選項卡切換
1.4.3
  發佈時間：2017年12月22日
  更新內容：
    1.修復CRUL口令
    2.提升操作體驗
1.4.2
  發佈時間：2017年12月15日
  更新內容：
    1.修復CRUL口令
    2.渲染菜單列表顏色
1.4.1
  發佈時間：2017年12月13日
  更新內容：
    1.修復CRUL口令
    2.修復DELETE類型請求部分存在404問題
1.4.0
  發佈時間：2017年12月14日
  更新內容：
    1.PATCH無法正確渲染
1.3.9
  發佈時間：2017年9月17日 
  更新內容：
    1.修復對象深度拷貝
1.3.8
  發佈時間：2017年12月8日 
  更新內容：
    1. 解決1.1.0發版中的bug    
1.1.0
  發佈時間：2017年12月1日
  更新內容：
    1. 完成基礎功能

重寫UI

操作風格 - 2.0.2 版本

# 2.0.3 版本新特性（開啓後訪問 swagger-ui.html 會自動路由到登陸頁面，保障接口信息不被暴露）
spring.swagger.security.filter-plugin=true
# 配置賬號密碼
spring.swagger.security.username=battcn
spring.swagger.security.password=battcn

操作風格 - 2.0.1 版本

# 配置
spring.swagger.api-key.key-name=myToken
# 2.0.1 版本新特性 （支持可選的 Bean 驗證插件）
spring.swagger.validator-plugin=false
# 定義全局響應返回
spring.swagger.global-response-messages.POST[0].code=400
spring.swagger.global-response-messages.POST[0].message=server response 400
spring.swagger.global-response-messages.POST[1].code=404
spring.swagger.global-response-messages.POST[1].message=server response 404

操作風格 - 1.4.3支持

接口說明：摺疊式Model

接口說明：摺疊式表單響應內容，告別長長的滾動條

在線調試

配置說明

spring.swagger.enabled：提供該配置目的是方便多環境關閉，一般生產環境中不會暴露它，這時候就可以通過 java -jar xx.jar --spring.swagger.enabled=false 動態關閉，也可以在多環境配置寫好

properties

spring.swagger.enabled=是否啓用swagger，默認：true
spring.swagger.title=標題
spring.swagger.description=描述信息
spring.swagger.version=版本
spring.swagger.license=許可證
spring.swagger.licenseUrl=許可證URL
spring.swagger.termsOfServiceUrl=服務條款URL
spring.swagger.contact.name=維護人
spring.swagger.contact.url=維護人URL
spring.swagger.contact.email=維護人email
spring.swagger.base-package=swagger掃描的基礎包，默認：全掃描
spring.swagger.base-path=需要處理的基礎URL規則，默認：/**
spring.swagger.exclude-path=需要排除的URL規則，默認：空
spring.swagger.host=文檔的host信息，默認：空
spring.swagger.globalOperationParameters[0].name=參數名
spring.swagger.globalOperationParameters[0].description=描述信息
spring.swagger.globalOperationParameters[0].modelRef=指定參數類型
spring.swagger.globalOperationParameters[0].parameterType=指定參數存放位置,參考ParamType:(header,query,path,body,form)
spring.swagger.globalOperationParameters[0].required=指定參數是否必傳，默認false
#下面分組是
spring.swagger.groups.<name>.basePackage=swagger掃描的路徑
#比如
spring.swagger.groups.基礎信息.basePackage=com.battcn.controller.basic

# 關閉 JSR
spring.swagger.validator-plugin=false
# 全局消息體
spring.swagger.global-response-messages.GET[0].code=400
spring.swagger.global-response-messages.GET[0].message=server response 400
spring.swagger.global-response-messages.POST[0].code=400
spring.swagger.global-response-messages.POST[0].message=server response 400
spring.swagger.global-response-messages.POST[1].code=404
spring.swagger.global-response-messages.POST[1].message=server response 404

yaml

以下爲 application.yml 配置示例

spring:
  swagger:
    enabled: true
    title: 標題
    description: 描述信息
    version: 系統版本號
    contact:
      name: 維護者信息
    base-package: swagger掃描的基礎包，默認：全掃描(分組情況下此處可不配置)
    #全局參數,比如Token之類的驗證信息可以全局話配置
    global-operation-parameters:
    -   description: 'Token信息,必填項'
        modelRef: 'string'
        name: 'Authorization'
        parameter-type: 'header'
        required: true
    groups:
      basic-group:
        base-package: com.battcn.controller.basic
      system-group:
        base-package: com.battcn.controller.system

貢獻者

Levin：[email protected]

• 個人博文：http://blog.battcn.com

_Rock：[email protected]

常用註解說明

• @Api:一般用於Controller中,用於接口分組。（如：@Api(value = "用戶接口", description = "用戶接口", tags = {"1.1.0"})

• @ApiOperation:接口說明,用於api方法上。（如： @ApiOperation(value = "用戶查詢", notes = "根據ID查詢用戶信息")）

• @ApiImplicitParam:參數說明,適用於只有一個請求參數,主要參數

• @ApiImplicitParams:多個參數說明,主要參數參考上面@ApiImplicitParam

• @ApiModel:實體類說明

• @ApiModelProperty：實體參數說明

如何參與

有興趣的可以聯繫本人（Pull Request），參與進來一起開發，美化UI與配置項一起完善