前言
前后端分離開發模式中，api文檔是最好的溝通方式。今天就來說一說如何整合Swagger生成一套漂亮、美觀、實用的接口文檔。
源碼傳送門：
https://gitee.com/huoqstudy/xiliu-admin.git
一、Swagger介紹
Swagger 是一個規范和完整的框架，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務，它有著如下的優點：
1. 及時性 (接口變更后，能夠及時準確地通知相關前后端開發人員)
2. 規范性 (并且保證接口的規范性，如接口的地址，請求方式，參數及響應格式和錯誤信息)
3. 一致性 (接口信息一致，不會出現因開發人員拿到的文檔版本不一致，而出現分歧)
4. 可測性 (直接在接口文檔上進行測試，以方便理解業務)
二、配置Swagger
1. 添加依賴
<!--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>
2. 創建Swagger2配置文件
代碼如下（示例）：
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket apiConfig() {
return new Docket(DocumentationType.SWAGGER_2)
// 調用apiInfo方法,創建一個ApiInfo實例,里面是展示在文檔頁面信息內容
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//大標題
.title("接口文檔")
//詳細描述
.description("接口文檔")
//版本
.version("1.0")
//作者
.contact(new Contact("xiliu", "http://www.xxx.com", "[email protected]"))
.build();
}
}
3. 重啟服務查看接口
訪問路徑：
http://localhost:8081/swagger-ui.html ，出現生成的文檔頁面。但是作為一個有審美追求的人，這ui也太難看了吧，果斷放棄，更換成Knife4j
4. 使用Knife4j
Knife4j的前身是swagger-bootstrap-ui，前身swagger-bootstrap-ui是一個純swagger-ui的ui皮膚項目。但是隨著項目的發展,面對越來越多的個性化需求，不得不編寫后端JAVA代碼以滿足新的需求，因此，項目正式更名為knife4j,取名knife4j是希望它能像一把匕首一樣小巧、輕量，并且功能強悍，更名也是希望把她做成一個為Swagger接口文檔服務的通用性解決方案，不僅僅只是專注于前端Ui前端。
4.1 添加依賴
需要刪除原來引用的swagger依賴
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.7</version>
</dependency>
4.2 修改配置類
@Configuration
@EnableSwagger2WebMvc
public class Swagger2Config {
@Bean(value = "defaultApi2")
public Docket defaultApi2() {
Docket docket=new Docket(DocumentationType.SWAGGER_2)
.apiInfo(new ApiInfoBuilder()
.title("接口文檔")
.description("# 接口文檔")
.termsOfServiceUrl("http://www.xx.com/")
.contact("[email protected]")
.version("1.0")
.build())
//分組名稱
.groupName("2.X版本")
.select()
//這里指定Controller掃描包路徑
.apis(RequestHandlerSelectors.basePackage("com.java.xiliu"))
.paths(PathSelectors.any())
.build();
return docket;
}
/*@Bean
public Docket apiConfig() {
return new Docket(DocumentationType.SWAGGER_2)
// 調用apiInfo方法,創建一個ApiInfo實例,里面是展示在文檔頁面信息內容
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//大標題
.title("接口文檔")
//詳細描述
.description("接口文檔")
//版本
.version("1.0")
//作者
.contact(new Contact("xiliu", "http://www.xxx.com", "[email protected]"))
.build();
}*/
}
4.3 重啟服務查看接口
訪問地址：
http://localhost:8081/doc.html，這個ui界面看起來就更美觀，更符合國人的使用習慣。
5. 定義接口說明和參數說明
定義在類上：@Api
定義在方法上：@ApiOperation
定義在參數上：@ApiParam
@Api(tags = "用戶管理")
@RestController
@RequestMApping("/ucenter/member")
public class MemberController {
@Autowired
private MemberService memberService;
@ApiOperation(value = "所有用戶列表")
@GetMapping(value = "/getAll")
public List<Member> list(){
return memberService.list(null);
}
@ApiOperation(value = "根據id刪除用戶")
@PostMapping(value = "del/{memberId}")
public boolean deleteById(
@ApiParam(name = "memberId", value = "用戶ID", required = true)
@PathVariable Long memberId){
return memberService.removeById(memberId);
}
@ApiOperation(value = "保存用戶")
@PostMapping(value = "save")
public boolean save(
@ApiParam(name = "member", value = "用戶對象json", required = true)
@RequestBody Member member){
if (null == member.getMemberId()) {
return memberService.save(member);
}
return memberService.updateById(member);
}
}
總結
感謝大家的閱讀，以上就是今天要講的內容，本文簡單介紹了如何整合Swagger生成api接口文檔，雖然很多人噴Swagger，不好用，基于注解，代碼入侵很強，等等 很多原因。但總體來看，swagger發展至今，包括在各個語言，NodeJs、.net、java、php等等，它可以說是一個有些接口規范的東西，從開始，到一步步規范，其實是一個很艱難的過程，任何事物，都不是盡善盡美的，swagger也是一樣，至少它給這么多語言提供了一種文檔生成的解決方案，其價值就遠超它本身的缺點。
最后弱弱地問一句，你們的項目用swagger了嗎？
