在之前開發時，前端人員總是說：“調好的參數怎么改了？接口不通了，能不能說一下”
我說：“1.文檔不夠詳情，我怎么返回你所想要的數據 2.我改完接口也告訴你了 3.這樣吧！我以后改接口直接告訴你調式”
后來我看了一篇文章，既可以解決前后端的矛盾，也可以提高工作效率 這就是Swagger
一：swagger是什么？
二：為什么使用swagger？
三：如何搭建一個swagger？
四：在項目中如何集成swagger？
五：是那個用swagger需要注意的問題
六：總結
一：Swagger是什么？
Swagger是一款RESTFUL接口的文檔在線自動生成+功能測試功能軟件。Swagger是一個規范和完整的框架，用於生成、描述、調用和可視化RESTfu風格的web服務。目標是使客戶端和文件系統作為服務器一同樣的速度來更新文件的方法，參數和模型緊密集成到服務器。這個解釋簡單點來講就是說，swagger是一款可以根據restful風格生成的接口開發文檔，並且支持做測試的一款中間軟件。
二：為什么使用swagger？
1.對於后端開發人員來說
- 不用再手寫Wiki接口拼大量參數，避免手寫錯誤
- 對代碼侵入性低，采用全注解的方式，開發簡單
- 方法參數名修改、新增、減少參數都可以直接生效，不用手動維護
- 缺點：增加了開發成本，寫接口還得再寫一套參數配置
2.對前端開發來說
- 后端只需要定義好接口，會自動生成文檔，接口功能、參數一目了然
- 聯調方便，如果出了問題，直接測試接口，實時檢查參數和返回值，就可以快速定位是前端還是后端的問題
3.對於測試
- 但對於測試沒有前端界面UI的功能，可以直接用它來測試接口
- 操作簡單，不用了解具體代碼就可以操作
三：如何搭建一個swagger？
- 在引入swagger的依賴，目前推薦使用2.7.0版本的，因為2.6.0版本有bug，而其他版本有沒有經驗驗證
①引入swagger 依賴庫
<!--swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
②springboot整合swagger
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket productApi(){
return new Docket(DocumentationType.SWAGGER_2).
apiInfo(apiInfo()).
select().
apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).//添加ApiOpentaion注解的被掃描
paths(PathSelectors.any()).
build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder().
title("swagger和springboot整合").
description("swagger的api文檔").
version("1.0").build();
}
}
swagger的注解：
swagger的核心在於注解，接下來就着重說一下swagger的注解
| 注解名稱 | 注解含義 | 注解使用地方 |
注解參數 | 參數含義 |
| @EnableSwagger2 | 開啟swagger注解 | 配置類上 | 無 | 無 |
| @Api | 標識swagger識別的類 | Controller類上 | value tags description
|
url的路徑值 如果設置這個值、value的值會被覆蓋 對api資源的描述
|
| @ApiIgore | 屏蔽顯示某個Controller，開啟后在swagger上不會顯示 | COntroller類上 | value | 值 |
| @ApiOperation | 標識swagger識別的方法 | Controller類中的方法 | value tags description basePath position produces consumes protocols authorizations hidden response responseContainer httpMethod code extensions notes |
url的路徑值 如果設置這個值、value的值會被覆蓋 對api資源的描述 基本路徑可以不配置 如果配置多個Api 想改變顯示順序位置 For example，"application/json，application/xml" For example，"application/json，application/xml" Possible values:http,https,ws,wss 高級特性認證時配置 配置為true將在文檔中隱藏 返回的對象 這些對象是有效的“List”，“Set”or “Map”，其他無效 “GET”、“HEAD”、“POST”、“PUT”、“DELETE”、“OPTIONS”and "PATCh" http的狀態碼 默認200 擴展屬性 用於提示內容 |
| @ApiImpliciParam | 修飾方法中的參數 | 用在@ApiImplicitParams注解中對，指定一個請求參數的各個方面 | paramType name value dataType required defaultValue |
參數放在哪個地方 參數代表的含義 參數名稱 參數類型，有String/int，無用 是否必要 參數的默認值 |
| @ApiImpliciParams | 修飾方法中的參數 | 用在方法上包含一組參數說明 |
@ApiImpliciParam | ApiImpliciParam的數組集合 |
| @ApiResponse | 修飾方法的返回值 |
方法上或方法的參數上 | code message class |
方法返回值狀態碼 方法返回值信息 方法返回class |
| @ApiResponses | 響應集配置 |
方法上或參數上 | @ApiResponse | ApiResponse的數組集合 |
| @ApiParam | 映射方法上的參數 | 方法的參數上 | name value defaultValue allowableValues required access allowMutiple hidden example |
屬性名稱 屬性值 默認屬性值 可以不配置 是否屬性必填 不過多描述 默認為false 隱藏該屬性 舉例子 |
| @ApiModel |
用於類，表示對類進行說明，用於參數用實體類接受 | 類上 | value description |
類名 描述 |
| @ApiModelProperty | 標識一個類的屬性 | 類的字段上 | value name dateType required example hidden |
字段說明 重寫屬性名字 重寫屬性類型 是否必填 舉例子 隱藏 |
四：在項目中如何集成swagger？
①在controller中使用注解
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@RestController
@Api(value = "測試TTestController",tags = {"測試訪問接口"})
@RequestMapping("test")
public class TTestController {
@ApiOperation(value = "添加測試數據")
@PostMapping("/insertInfo")
@ApiResponses(value = {
@ApiResponse(code = 1000,message = "成功"),
@ApiResponse(code = 1001,message = "失敗"),
@ApiResponse(code = 1002,message = "缺少參數",response = TestUser.class)
})
public String insertInfo(@ApiParam("用戶名字") @RequestParam("userName") String userName,
@ApiParam(value = "年齡",allowEmptyValue = true) @RequestParam("age") Integer age){
String username = userName;
Integer Age = age;
return username+age.toString();
}
}
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel(value = "testUser",description = "用戶")
public class TestUser {
@ApiModelProperty(value = "用戶名字", name = "userName", dataType = "String")
private String userName;
private Integer age;
public Integer getAge() {
return age;
}
public void setAge(Integer age) {
this.age = age;
}
public String getUserName() {
return userName;
}
public void setUserName(String userName) {
this.userName = userName;
}
}
②訪問本地鏈接
http://localhost:8080/swagger-ui.html
五：是那個用swagger需要注意的問題
①:對於只有一個HttpServletRequest參數的方法,如果參數小於5個，推薦使用 @ApiImplicitParams的方式單獨封裝每一個參數；如果參數大於5個，采用定義一個對象去封裝所有參數的屬性，然后使用@APiParam的方式
②默認的訪問地址：ip:port/swagger-ui.html#/,但是在shiro中,會攔截所有的請求，必須加上默認訪問路徑（比如項目中，就是
ip:port/context/swagger-ui.html#/），然后登陸后才可以看到
③在GET請求中，參數在Body體里面,不能使用@RequestBody。在POST請求，可以使用@RequestBody和@RequestParam，如果使用@RequestBody，對於參數轉化的配置必須統一
④ controller必須指定請求類型，否則swagger會把所有的類型(6種)都生成出來
⑤: swagger在生產環境不能對外暴露,可以使用@Profile({“dev”, “prod”,“pre”})指定可以使用的環境
六：總結
swagger作為一款輔助性的工具，能大大提升我們的和前端的溝通效率,接口是一個非常重要的傳遞數據的媒介，每個接口的簽名、方法參數都非常重要。一個良好的文檔非常重要，如果采用手寫的方式非常容易拼寫錯誤，而swagger可以自動化生成參數文檔，這一切都加快了我們的溝通效率。並且可以替代postman的作用。實在是開發編程必備良品啊。