Spring Boot 使用 Swagger 構建 RestAPI 介面文件
原始碼地址：https://github.com/laolunsi/spring-boot-examples
目前SpringBoot常被用於開發Java Web應用，特別是前後端分離專案。為方便前後端開發人員進行溝通，我們在SpringBoot引入了Swagger。
Swagger作用於介面，讓介面資料視覺化，尤其適用於Restful APi
本節分兩部分介紹，第一部分是SpringBoot引入Swagger的兩種方式，第二部分是詳細介紹在Web介面上應用Swagger的註解。
本篇文章使用SpringBoot 2.1.10.RELEASE和springfox-swagger 2.9.2
一、SpringBoot引入Swagger的兩種方式
目前SpringBoot有兩種使用Swagger的方式：
引入swagger原生依賴springfox-swagger2和springfox-swagger2-ui
引入國內Spring4All社群開發的依賴swagger-spring-boot-starter
Spring4All出品的依賴採取配置檔案的方式進行配置，而原生依賴是通過java config類來設定的。
1.1 原生配置Swagger
maven依賴：
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
swagger配置類：
/**
* swagger2配置類
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.example"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("基於Swagger構建的Rest API文件")
.description("更多請諮詢服務開發者eknown")
.contact(new Contact("空夜","http://www.eknown.cn","[email protected]"))
.termsOfServiceUrl("http://www.eknown.com")
.version("1.0")
.build();
}
}從這裡可以看出Swagger的一個缺點：無法通過SpringBoot的配置檔案進行配置，所以配置並不能靈活轉變。
spring4all社群出品的swagger-spring-boot-starter可以解決這個問題。
1.2 基於spring4all配置swagger
Spring4All社群的博主程式猿DD和小火兩個人開發了Spring Boot Starter Swagger，目前已經在maven官方倉庫上線了。
選擇第一個，引入該依賴：
<dependency> <groupId>com.spring4all</groupId> <artifactId>swagger-spring-boot-starter</artifactId> <version>1.9.0.RELEASE</version> </dependency>
這種方式的Swagger配置是通過application配置檔案進行的。下面給出一個示例：
server: port: 8106 swagger: base-path: /** base-package: 'com.example' title: 'spring-boot-swagger-demo' description: '基於Swagger構建的SpringBoot RESTApi 文件' version: '1.0' contact: name: '空夜' url: 'http://www.eknown.cn' email: '[email protected]'
二、應用Swagger構建介面視覺化
2.1 Controller類新增Swagger註解
下面給一個簡單的示例：
@Api(tags = "使用者管理")
@RestController
@RequestMapping(value = "user")
public class UserController {
// 模擬資料庫儲存的使用者
private static Map<Integer,User> userMap;
static {
userMap = new ConcurrentHashMap<>();
User user = new User(0,"admin",true,new Date());
userMap.put(user.getId(),user);
}
@ApiOperation("列表查詢")
@GetMapping(value = "")
public List<User> list() {
return new ArrayList<>(userMap.values());
}
@ApiOperation(value = "獲取使用者詳細資訊",notes = "路徑引數ID")
@GetMapping(value = "{id}")
public User detail(@PathVariable Integer id) {
return userMap.get(id);
}
@ApiOperation(value = "新增或更新使用者資訊",notes = "insert和update共用",response = User.class)
@PostMapping(value = "")
public User add(@RequestBody User user) {
if (user == null || user.getId() == null || !StringUtils.isEmpty(user.getName())
|| userMap.containsKey(user.getId())) {
return null;
}
user.setUpdateTime(new Date());
userMap.put(user.getId(),user);
return user;
}
@ApiOperation(value = "刪除使用者")
@DeleteMapping(value = "{id}")
public Boolean delete(@ApiParam(name = "使用者ID",required = true,example = "100") @PathVariable Integer id) {
if (userMap.containsKey(id)) {
userMap.remove(id);
return true;
}
return false;
}
}
2.2 引數實體類新增Swagger註解
實體類也需要新增一些註解，以便前端開發人員確定引數的意義、型別、示例等。
@ApiModel(description = "使用者類")
public class User {
@ApiModelProperty(value = "ID",example = "100")
private Integer id;
@ApiModelProperty(value = "姓名",example = "laolunsi")
private String name;
@ApiModelProperty(value = "是否啟用",example = "1")
private Boolean enable;
@ApiModelProperty("更新時間")
private Date updateTime;
public User(Integer id,String name,Boolean enable,Date updateTime) {
this.id = id;
this.name = name;
this.enable = enable;
this.updateTime = updateTime;
}
// ... ignore getter and setter methods
}
2.3 測試
啟動專案，訪問http://localhost:port/swagger-ui.html
如果存在server.servlet.context-path配置，那麼訪問地址是http://localhost:port/context-path/swagger-ui.html
這樣，介面就一目瞭然了，swagger還支援線上測試介面，與postman的作用類似。
好，到目前為止，我們已經成功在SpringBoot專案中整合了Swagger，這樣前後端開發對接就有了標準！
以上就是Spring Boot 使用 Swagger 構建 RestAPI 介面文件的詳細內容，更多關於Spring Boot 整合 Swagger的資料請關注我們其它相關文章！