SpringBoot整合Swagger管理API接口詳解

Swagger概念

• 傳統API文檔管理缺點:
  • 對API文檔更新時需要通知前端人員,導緻文檔更新交流不及時,API接口傳回資訊不明确
  • 缺乏線上接口測試,需要使用額外的API測試工具:postman,SoapUI
  • 接口文檔太多,不便于管理
• 為了解決傳統API文檔維護問題,友善進行測試背景RESTful接口并實作動态更新,引入Swagger接口工具
• Swagger工具優點:
  • 功能豐富: 支援多種注解,自動生成接口文檔界面,支援在界面測試API接口功能
  • 及時更新: 在開發工程中編寫好注釋,就可以及時更新API文檔
  • 整合簡單: 通過添加pom.xml依賴和簡單配置,内嵌于應用中就可同時釋出API接口文檔界面,不需要部署獨立服務

整合Swagger生成API文檔

SpringBoot項目

1.引入Maven依賴springfox-swagger2和springfox-swagger-ui
2.建立SwaggerConfig類實作Swagger生成API文檔邏輯:
生成API文檔的掃包範圍apis
建立API文檔資訊ApiInfoBuilder.title("文檔标題").description("文檔描述").termOfServiceUrl("網址Url").version("版本号").build()
3.在SwaggerConfig類上标注@EnableSwagger2注解開啟Swagger功能
4.建立SwaggerController類,在類中建立API接口
5.在SwaggerController類上标注@Api("接口描述")注解作整體接口描述
6.在SwaggerController類裡API接口上被标注@ApiOperation("具體接口描述")注解,标注@ApiImplicitParam(name="參數名稱",value="參數值",required=true,dataType="參數類型")
7.<注意>不要在API接口類上标注RequestMapping注解(這樣會生成所有請求接口,沒有可讀性):
根據相應的請求方式,标注@XxxMapping注解
8.建立啟動類啟動           

微服務叢集項目

• 在微服務項目中,Swagger是在每個服務進行內建的,需要将整個微服務中的Swagger進行合成到同一台伺服器上:
  • 使用Zuul+Swagger實作
  • 使用Nginx+Swagger實作,以項目類型跳轉到不同的接口文檔

使用Zuul+Swagger實作微服務整個API接口文檔的管理

• SpringBoot中支援對Swagger進行管理,隻需要在Zuul網關中添加對應服務的Swagger文檔即可
• 原理: 每個獨立服務都會內建Swagger自動生成API文檔,前端發送服務請求到Zuul網關,Zuul根據請求調用對應服務的Swagger查詢API接口

在各個微服務的類中:
1.在各個微服務中引入SpringBoot支援的Swagger依賴swagger-spring-boot-starter
2.配置檔案,可省略不寫:
(swagger.base-package=需要生成文檔的包名)
3.在微服務的主類上标注@EnableSwagger2Doc文檔注解,生成Swagger文檔,
4.在微服務的主類上标注@Api("接口描述")注解作整體接口描述
5.在SwaggerController類裡API接口上被标注@ApiOperation("具體接口描述")注解
6.标注@ApiImplicitParam(name="參數名稱",value="參數值",required=true,dataType="參數類型")

在Zuul網關類中:
1.引入SpringBoot支援的Swagger依賴swagger-spring-boot-starter
2.在Zuul網關類中建立SwaggerAPI文檔的配置類邏輯方法
添加文檔來源:resource.add(swaggerResource("文檔名稱","API接口文檔","版本号"))
3.在SwaggerAPI文檔的配置類上标注@Component将配置類添加到容器中
4.在Zuul網關類上标注@EnableSwagger2Doc開啟Swagger文檔注解