簡介
Swagger 是一個可以用來構建API服務文檔的工具，并且API文檔可以和代碼服務實時更新，保持一致，提供了UI界面可以直接查看文檔。同時還可以進行功能測試。
在Spring Boot項目中集成使用
1.新建項目并添加相關依賴
- Springfox-swagger2
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
- Springfox-swagger2-ui
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2-ui</artifactId>
<version>2.4.0</version>
</dependency>
2.添加配置類
@EnableSwagger2
@Configuration
public class SwaggerConfig {
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// 當前包路徑
.apis(RequestHandlerSelectors.basePackage("cn.leon.leonswagger.controller"))
.paths(PathSelectors.any())
.build();
}
//構建api文檔的詳細信息函數
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//頁面標題
.title("Leon測試Swagger")
//創建人
.contact(new Contact("Leon", "http://www.dujinghua.cn", ""))
//版本號
.version("1.0")
//描述
.description("API 描述")
.build();
}
}
3.為服務類添加注解
為提供接口服務的Controller類添加注解：@Api
@Api("swagger測試相關api")
public class LeonController {
}
4.為方法添加注解
在上面創建的LeonController類中添加方法,并在方法上添加相關注解：
/**
* Get請求測試
*/
@ApiOperation(value = "根據id查詢商品詳情", notes = "查詢某個商品的詳細信息")
@ApiImplicitParam(name = "id", value = "商品id", paramType = "path", required = true, dataType ="String")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用戶id", dataType = "String", paramType = "path", example = "1112")
})
@ApiResponses({
@ApiResponse(code = 500, message = "服務器內部錯誤"),
@ApiResponse(code = 404, message = "找不到請求路徑")
})
@RequestMapping(value = "getGoods/{id}", method = RequestMethod.GET)
public String GetGoods(@PathVariable String id) {
return "Leon-商品ID : " + id;
}
5.訪問文檔
運行項目，訪問地址：http://localhost:8080/swagger-ui.html 可以看到如下界面：
點擊leon-controller可以看到方法的描述：
詳細參數介紹
@EnableSwagger2 @Configuration
配置類需要添加的注解，聲明為Swagger
@ApiOperation
指定接口方法的說明，如果方法不加此注解，說明默認為方法名稱：
@ApiImplicitParams @ApiImplicitParam
接口詳細描述的參數信息：
其中 ApiImplicitParam 為具體的參數，里面的配置 paramType 需要注意：
paramType代表參數放在哪個地方
- header-->請求參數的獲取：@RequestHeader
- query-->請求參數的獲取：@RequestParam
- path（用于restful接口）-->請求參數的獲取：@PathVariable
- body（不常用）
- form（不常用）
@ApiResponses
接口返回信息描述：
測試
除了用作靜態接口文檔，swagger還可以進行測試，直接看到接口調用的返回結果，在參數中輸入數值，然后點擊 try it out 按鈕，就可以查看詳細調用結果：
注：如果發現請求返回結果有問題，可以先查看請求的完整地址，是否是正確的格式
如果接口方法中不加任何描述，那么會按照方法的參數默認生成描述，并且參數都是必須的（requeired）,測試的不輸入參數會提示報錯：
返回json數據
目前接口返回一般都是json數據，在Swagger中，可以指定返回為json格式數據，在ApiOperation注解中添加produces：
@ApiOperation(value = "根據id查詢商品詳情", notes = "查詢某個商品的詳細信息",produces = "application/json")
然后就可以看到：
在項目中添加JSON依賴：
<dependency>
<groupId>com.google.code.gson</groupId>
<artifactId>gson</artifactId>
<version>2.8.0</version>
</dependency>
然后返回數據時返回json格式數據：
@RequestMapping(value = "getGoods/{id}", method = RequestMethod.GET)
public String GetGoods(@PathVariable String id) {
String info = "Leon-商品ID : " + id;
JsonObject jsonObject = new JsonObject();
jsonObject.addProperty("info", info);
return jsonObject.toString();
}
重新在Swagger頁面中測試，可以看到返回結果為json：
在Spring Cloud項目中集成使用
在Spring Cloud中我們的服務都會注冊在Eureka Server中，如下所示：
此時當我們點擊紅框中的服務時，返回的是空，無法查看具體的服務信息，接下來在Spring Cloud集成Swagger。
首先為注冊到Eureka Server上的服務添加配置：
eureka:
client:
service-url:
defaultZone: http://root:123456@localhost:7776/eureka/
instance:
status-page-url: http://localhost:${server.port}/swagger-ui.html
然后重啟服務重新注冊即可，然后在注冊中心的界面，點擊該服務就可以自動跳轉到Swagger文檔主頁面
替代產品
除了使用Swagger提供項目API文檔，還有其他一些不錯的選擇。Swagger的好處是可以根據代碼變動隨時更新內容并且可以測試，但是也有一些不太方便的地方：
- 和代碼耦合在一起，是代碼看起來比較臃腫
- 如果代碼沒有寫完，那么接口文檔就無法完成
- 項目服務啟動才能訪問接口文檔，如果是公司內網開發，離開環境就無法查看。或者后端開發停掉服務，前端開發就看不到文檔了
這里介紹幾種其他的接口文檔方案,具體選中哪種每個團隊都會有不同的選擇：
Easy Mock
https://easy-mock.com/login
是一個可視化，并且能快速生成模擬數據的服務。可以在線生成模擬接口，能夠隨機產生數據，也支持結合Swagger使用
YApi
https://yapi.ymfe.org/
可視化操作配置，同樣非常方便
RAP
http://rapapi.org/org/index.do
阿里媽媽前端團隊出品的開源接口管理工具RAP第二代
