spring-boot-route（五）整合Swagger生成介面文件
阿新 • • 發佈：2020-10-06
目前，大多數公司都採用了前後端分離的開發模式，為了解決前後端人員的溝通問題，後端人員在開發介面的時候會選擇使用swagger2來生成對應的介面文件，swagger2提供了強大的頁面除錯功能，這樣可以有效解決前後端人員溝通難的問題。
下面我們使用SpringBoot結合swagger2生成Restful API文件。
### 一 搭建專案，引入依賴
新建一個`spring-boot-swaager`的專案，引入swaager2的依賴，由於swagger2的ui不是很美觀，這裡將使用開源的`swagger-bootstrap-ui`做為ui。
**引入依賴**
```java
```
**專案中配置swagger相關資訊**
```java
@Configuration
@EnableSwagger2
public class configuration {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.javatrip.swagger.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
// 標題
.title("某某專案介面文件")
// 描述
.description("swagger2介面文件使用演示")
// 版本
.version("1.0")
// 許可證
.license("MIT")
// 許可證地址
.licenseUrl("www.xx.com")
// 服務端地址
.termsOfServiceUrl("https://www.cnblogs.com/zhixie/")
// 聯絡資訊
.contact(new Contact("java旅途","https://www.cnblogs.com/zhixie/","[email protected]"))
.build();
}
}
```
**訪問路徑，檢視生成效果**
文章中使用的這個ui，介面文件地址為`ip:port/doc.html`，生成的文件資訊如下：
### 二 編寫Restful介面
**新建實體類**
```java
@ApiModel("使用者實體類")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Person {
@ApiModelProperty("姓名")
private String name;
@ApiModelProperty(value = "年齡")
private int age;
}
```
**新建Restful介面**
~~~java
@Api(tags = "使用者介面")
@RestController
@RequestMapping("person")
public class PersonController {
@ApiOperation(value = "獲取使用者列表",notes = "根據name獲取使用者列表")
@ApiImplicitParams({
@ApiImplicitParam(name = "name",value = "使用者姓名",dataType = "String",required = true),
@ApiImplicitParam(name = "age",value = "年齡",dataType = "int",required = true)
})
@GetMapping("/{name}")
public Person getPerson(@PathVariable("name") String name,@RequestParam int age){
return new Person(name,age);
}
@ApiOperation(value = "新增使用者",notes = "根據使用者實體類新增使用者")
@ApiImplicitParam(name = "person",value = "使用者實體類",dataType = "Person",required = true)
@PostMapping("add")
public int addPerson(@RequestBody Person person){
if(StringUtils.isEmpty(person)){
return -1;
}
return 1;
}
@ApiOperation(value = "更新使用者資訊",notes = "根據使用者實體更新使用者資訊")
@ApiImplicitParam(name = "person",value = "使用者實體類",dataType = "Person",required = true)
@PutMapping("update")
public int updatePerson(@RequestBody Person person){
if(StringUtils.isEmpty(person)){
return -1;
}
return 1;
}
@ApiOperation(value = "刪除使用者資訊",notes = "根據使用者名稱刪除使用者資訊")
@ApiImplicitParam(name = "name",value = "使用者姓名",dataType = "String",required = true)
@DeleteMapping("/{name}")
public int deletePerson(@PathVariable(name = "name") String name){
if(StringUtils.isEmpty(name)){
return -1;
}
return 1;
}
}
~~~
### 三 swagger文件簡介
我就直接用圖來表示了，這樣看著也更加直觀
swagger2註解對應到文件上的表現形式如上。swagger2支援線上除錯，開啟某個具體的介面，根據提示填寫對應的引數，點擊發送就可返回響應結果。
此是spring-boot-route系列的第五篇文章，這個系列的文章都比較簡單，主要目的就是為了幫助初次接觸Spring Boot 的同學有一個系統的認識。本文已收錄至我的[github](https://github.com/binzh303/spring-boot-route)，歡迎各位小夥伴`star`！
**github**：https://github.com/binzh303/spring-boot-route
## 點關注、不迷路
如果覺得文章不錯，歡迎**關注**、**點贊**、**收藏**，你們的支援是我創作的動力，感謝大家。
如果文章寫的有問題，請不要吝嗇，歡迎留言指出，我會及時核查修改。
如果你還想更加深入的瞭解我，可以微信搜尋「**Java旅途**」進行關注。回覆「**1024**」即可獲得學習視訊及精美電子書。每天7:30準時推送技術文章，讓你的上班路不在孤獨，而且每月還有送書活動，助你提升硬