SpringBoot - Swagger2的集成与使用教程（生成API接口文档）

作者：hangge | 2019-12-24 08:10

在前后端分离开发中，为了减少与其它团队的沟通成本，一般都会构建一份 RESTful API 文档来描述所有的接口信息。但传统的方式有许多弊端，不仅编写文档工作量巨大，而且维护不方便，测试也不方便（需要借助第三方工具，如 Postman 来测试）

为解决这些问题，我们可以使用 Swagger 2 来构建在线接口文档，下面通过样例进行演示。

一、基本介绍

1，什么是 Swagger 2

Swagger 2 是一个开源软件框架，可以帮助开发人员设计、构建、记录和使用 RESTful Web 服务，它将代码和文档融为一体，可以完美解决文档编写繁琐、维护不方便等问题。使得开发人员可以将大部分精力集中到业务中，而不是繁杂琐碎的文档中。

2，安装配置

（1）首先编辑项目的 pom.xml 文件，添加 Swagger 2 相关依赖：

注意：因为我这里引入的 swagger ui 是 2.7 以上的版本，所以还需要引入 guava，否则会因为 guava 兼容性问题造成项目启动报错（无法启动）

<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>
<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>20.0</version>
</dependency>

（2）接着创建 Swagger 2 的配置类，代码如下：

代码说明：

首先通过 @EnableSwagger2 注解开启了 Swagger 2，然后最主要的是配置一个 Docket。
通过 apis 方法配置要扫描的 controller 位置，通过 paths 方法配置路径。
在 apiInfo 中构建文档的基本信息，例如描述、联系人信息、版本、标题等。

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API测试文档")
                .description("DEMO项目的接口测试文档")
                .termsOfServiceUrl("http://www.hangge.com")
                .version("1.0")
                .contact(new Contact("航歌",
                        "http://www.hangge.com",
                        "hangge@hangge.com"))
                .build();
    }
}

二、使用样例

1，添加注解

（1）首先我们在 Controller 上添加相关的 @Api 注解：

（1）@Api 注解标注在类上用来描述整个 Controller 信息。
（2）@ApiOperation 注解标注在方法上，用来描述一个方法的基本信息。
（3）@ApiImplicitParam 注解标注在方法上，用来描述方法的参数。其中 paramType 是指方法参数的类型，有如下可选值：

path：参数获取方式为 @PathVariable
query：参数获取方式为 @RequestParam
header：参数获取方式为 @RequestHeader
body
form

（4）如果有多个参数，可以将多个参数的 @ApiImplicitParam 注解放到 @ApiImplicitParams 中。
（5）@ApiResponse 是对响应结果的描述。code 表示响应码，message 为相应的描述信息。如果有多个 @ApiResponse，则放在一个 @ApiResponses 中。
（6）@ApiIgnore 注解表示不对某个接口生成文档。

@RestController
@Api(tags = "用户数据接口")
public class UserController {
    @ApiOperation(value ="查询用户", notes = "根据 id 查询用户")
    @ApiImplicitParam(paramType = "path", name = "id", value = "用户 id", required = true)
    @GetMapping("/user/{id}")
    public String getUserById(@PathVariable Integer id){
        return "查找的用户id是：" + id;
    }

    @ApiOperation(value = "新增用户", notes = "根据传入的用户名和密码添加一个新用户")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "username",
                    value = "用户名", required = true, defaultValue = "test"),
            @ApiImplicitParam(paramType = "query", name = "password",
                    value = "密码", required = true, defaultValue = "123")
    })
    @PostMapping("/user")
    public String addUser(@RequestParam String username, @RequestParam String password) {
        return "新增用户：" + username + " " + password;
    }

    @ApiOperation(value = "删除用户", notes = "根据 id 删除用户")
    @ApiResponses({
            @ApiResponse(code = 200, message = "删除成功！"),
            @ApiResponse(code = 500, message = "删除失败！")
    })
    @DeleteMapping("/user/{id}")
    public Integer deleteUserById(@PathVariable Integer id) {
        return id;
    }

    @ApiOperation(value = "修改用户", notes = "传入用户信息进行更新修改")
    @PutMapping("/user")
    public String updateUser(@RequestBody User user){
        return user.toString();
    }

    @ApiIgnore
    @GetMapping("/user/test")
    public String test() {
        return "这是一个测试接口，不需要在api文档中显示。";
    }
}

（2）接着对模型对象也添加相关的注解：

由于在上面 Controller 里的 updateUser 方法中，使用 @RequestBody 注解来接收数据，此时可以通过 @ApiModel 注解和 @ApiModelProperty 注解配置 User 对象的描述信息。

@Getter
@Setter
@ToString
@ApiModel(value = "用户实体类", description = "用户信息描述类")
public class User {
    @ApiModelProperty(value = "用户id")
    private Integer id;

    @ApiModelProperty(value = "用户名")
    private String username;

    @ApiModelProperty(value = "用户密码")
    private String password;
}

2，查看接口文档

（1）启动 Spring Boot 项目，在浏览器中输入 http://localhost:8080/swagger-ui.html 即可看到接口文档。

（2）展开任意一个接口描述，单击 Try it out 按钮后，可以实现对该接口的测试。

附：使用 swagger-bootstrap-ui 代替原来的 ui

（1）如果觉得原先使用的 swagger ui 比较丑、或者不方便的话，可以试试 swagger-bootstrap-ui。只需修改 pom.xml 文件，将原来的 springfox-swagger-ui 依赖替换成 swagger-bootstrap-ui 即可。

注意：1.9.6 是 swagger-bootstrap-ui 的最后一个版本。由于各种原因，原作者又另起一新的项目：knife4j-spring-ui。knife4j 会包含 swagger-bootstrap-ui 的所有特性，并增加许多新特性，有兴趣的小伙伴可以尝试一下。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>
<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>20.0</version>
</dependency>

（2）项目启动后，通过 http://localhost:8080/doc.html 地址即可访问新的 UI 界面：

（3）可以看到 bootstrap 风格的界面样式比原先的清爽、高效许多：

SpringBoot / Cloud