SpringBoot整合Swagger實戰

源碼地址：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的方式：

1. 引入swagger原生依賴springfox-swagger2和springfox-swagger2-ui
2. 引入國內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", "[e-mail]"))
                .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: '[e-mail]'

---

二、應用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，這樣前后端開發對接就有了標准！