Spring Boot 使用 Swagger 構(gòu)建 RestAPI 接口文檔

更新時(shí)間：2020年10月26日 09:25:36 作者：空夜

這篇文章主要介紹了Spring Boot 使用 Swagger 構(gòu)建 RestAPI 接口文檔，幫助大家更好的理解和使用Spring Boot框架，感興趣的朋友可以了解下

源碼地址：https://github.com/laolunsi/spring-boot-examples

目前SpringBoot常被用于開發(fā)Java Web應(yīng)用，特別是前后端分離項(xiàng)目。為方便前后端開發(fā)人員進(jìn)行溝通，我們?cè)赟pringBoot引入了Swagger。

Swagger作用于接口，讓接口數(shù)據(jù)可視化，尤其適用于Restful APi

本節(jié)分兩部分介紹，第一部分是SpringBoot引入Swagger的兩種方式，第二部分是詳細(xì)介紹在Web接口上應(yīng)用Swagger的注解。

本篇文章使用SpringBoot 2.1.10.RELEASE和springfox-swagger 2.9.2

一、SpringBoot引入Swagger的兩種方式

目前SpringBoot有兩種使用Swagger的方式：

引入swagger原生依賴springfox-swagger2和springfox-swagger2-ui

引入國(guó)內(nèi)Spring4All社區(qū)開發(fā)的依賴swagger-spring-boot-starter

Spring4All出品的依賴采取配置文件的方式進(jìn)行配置，而原生依賴是通過(guò)java config類來(lái)設(shè)置的。

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構(gòu)建的Rest API文檔")
    .description("更多請(qǐng)咨詢服務(wù)開發(fā)者eknown")
    .contact(new Contact("空夜", "http://www.eknown.cn", "eknown@163.com"))
    .termsOfServiceUrl("http://www.eknown.com")
    .version("1.0")
    .build();
 }
}

從這里可以看出Swagger的一個(gè)缺點(diǎn)：無(wú)法通過(guò)SpringBoot的配置文件進(jìn)行配置，所以配置并不能靈活轉(zhuǎn)變。

spring4all社區(qū)出品的swagger-spring-boot-starter可以解決這個(gè)問(wèn)題。

1.2 基于spring4all配置swagger

Spring4All社區(qū)的博主程序猿DD和小火兩個(gè)人開發(fā)了Spring Boot Starter Swagger，目前已經(jīng)在maven官方倉(cāng)庫(kù)上線了。

選擇第一個(gè)，引入該依賴：

<dependency>
 <groupId>com.spring4all</groupId>
 <artifactId>swagger-spring-boot-starter</artifactId>
 <version>1.9.0.RELEASE</version>
</dependency>

這種方式的Swagger配置是通過(guò)application配置文件進(jìn)行的。下面給出一個(gè)示例：

server:
 port: 8106
swagger:
 base-path: /**
 base-package: 'com.example'
 title: 'spring-boot-swagger-demo'
 description: '基于Swagger構(gòu)建的SpringBoot RESTApi 文檔'
 version: '1.0'
 contact:
 name: '空夜'
 url: 'http://www.eknown.cn'
 email: 'eknown@163.com'

二、應(yīng)用Swagger構(gòu)建接口可視化

2.1 Controller類添加Swagger注解

下面給一個(gè)簡(jiǎn)單的示例：

@Api(tags = "用戶管理")
@RestController
@RequestMapping(value = "user")
public class UserController {

 // 模擬數(shù)據(jù)庫(kù)存儲(chǔ)的用戶
 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 = "獲取用戶詳細(xì)信息", notes = "路徑參數(shù)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 參數(shù)實(shí)體類添加Swagger注解

實(shí)體類也需要添加一些注解，以便前端開發(fā)人員確定參數(shù)的意義、類型、示例等。

@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("更新時(shí)間")
 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 測(cè)試

啟動(dòng)項(xiàng)目，訪問(wèn)http://localhost:port/swagger-ui.html

如果存在server.servlet.context-path配置，那么訪問(wèn)地址是http://localhost:port/context-path/swagger-ui.html