鸣谢：https://developer.ibm.com/zh/articles/j-using-swagger-in-a-spring-boot-project/

完整代码： https://github.com/ganchaoyang/spring-tutorial/tree/master/sb-swagger

1.准备SpringBootWeb项目

在这一步我们将准备一个基础的 Spring Boot 的 Web 项目，并且提供后面所需要的所有 API。

1.1创建一个空的 Spring Boot 项目

参考文章：https://editor.csdn.net/md/?articleId=114417791

1.2添加依赖

由于创建的是一个 Web 项目，所以我们需要依赖 Spring Boot 的 Web 组件，只需要在 pom.xml 增加如下内容即可：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

1.3编写接口

1.3.1首先我们创建三个包

• cn.itweknow.sbswagger.controller

• cn.itweknow.sbswagger.testcontroller

• cn.itweknow.sbswagger.model

1.3.2 在 controller 包下新建 UserController.java

package cn.itweknow.sbswagger.controller;

import cn.itweknow.sbswagger.model.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

/**
 * Created by 背影男神 on 2021/3/5.
 */
@RestController
@RequestMapping("/user")
@Api(tags = "用户相关接口", description = "提供用户相关的Rest API" )
public class UserController {
    @ApiOperation("新增用户接口")
    @PostMapping("/add")
    public boolean addUser(@RequestBody User user){
        return false;
    }

    @ApiOperation("通过id查找用户接口")
    @GetMapping("/find/{id}")
    public User findById(@PathVariable("id") int id){
        return new User();
    }

    @ApiOperation("更新用户信息接口")
    @PutMapping("update")
    public boolean update(@RequestBody User user){
        return true;
    }

    @ApiOperation("删除用户接口")
    @DeleteMapping("delete/id")
    @ApiIgnore
    public boolean delete(@PathVariable("id") int id){
        return true;
    }
}

1.3.3 在 testcontroller 包下新建 TestController.java 类

package cn.itweknow.sbswagger.testcontroller;

import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * Created by 背影男神 on 2021/3/5.
 */
@RestController
@RequestMapping("/test")
@Api(tags = "测试相关接口", description = "提供测试相关的Rest APi")
public class TestController {

    @GetMapping("/test")
    public void test(){
        System.out.println("test");
    }
}

1.3.4 在 model 包下新建 User.java 类

package cn.itweknow.sbswagger.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

/**
 * Created by 背影男神 on 2021/3/5.
 */
@ApiModel("用户实体")
public class User {
    /**
     * 用户Id
     */
    @ApiModelProperty("用户id")
    private int id;

    /**
     * 用户名
     */
    @ApiModelProperty("用户姓名")
    private String name;

    /**
     * 用户地址
     */
    @ApiModelProperty("用户地址")
    private String address;

    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }
}

2. 集成Swagger2

经过上面的步骤，我们已经拥有了五个接口，分别是:

1. /user/add：新增用户。
2. /user/find/{id}：根据 id 查询用户。
3. /user/update：更新用户。
4. /user/delete/{id}：根据 id 删除用户。
5. /test/test：测试接口。

下面我们将通过集成 Swagger2，然后为这 5 个 Rest API 自动生成接口文档。

2.1 添加依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

2.2 Java配置

Springfox 提供了一个 Docket 对象，让我们可以灵活的配置 Swagger 的各项属性。

新建一个cn.itweknow.sbswagger.conf.SwaggerConfig.java 类，并增加如下内容:

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

注意:
@Configuration 是告诉 Spring Boot 需要加载这个配置类
@EnableSwagger2 是启用 Swagger2，如果没加的话自然而然也就看不到后面的验证效果了。

2.3.验证

至此，我们已经成功的在 Spring Boot 项目中集成了 Swagger2，启动项目后，我们可以通过在浏览器中访问 http://localhost:8080/v2/api-docs 来验证，您会发现返回的结果是一段 JSON 串，可读性非常差。幸运的是 Swagger2 为我们提供了可视化的交互界面 SwaggerUI，下面我们就一起来试试吧。

3.集成Swagger UI

3.1 添加依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

3.2 访问验证

其实就只需要添加一下依赖就可以了，我们重新启动一下项目，然后在浏览器中访问 http://localhost:8080/swagger-ui.html 就可以看到如下的效果了:

可以看到虽然可读性好了一些，但对接口的表述还不是那么的清楚，接下来我们就通过一些高级配置，让这份文档变的更加的易读。

4. 高级配置

4.1 文档相关描述配置

1.通过在控制器类上增加 @Api 注解，可以给控制器增加描述和标签信息。

@Api(tags = "用户相关接口", description = "提供用户相关的 Rest API")
public class UserController

2.通过在接口方法上增加 @ApiOperation 注解来展开对接口的描述，当然这个注解还可以指定很多内容，我们在下面的相关注解说明章节中详细解释。

@ApiOperation("新增用户接口")
@PostMapping("/add")
public boolean addUser(@RequestBody User user) {
    return false;
}

3.实体描述，我们可以通过 @ApiModel 和 @ApiModelProperty 注解来对我们 API 中所涉及到的对象做描述。

@ApiModel("用户实体")
public class User {
    @ApiModelProperty("用户 id")
private int id;
}

4.文档信息配置，Swagger 还支持设置一些文档的版本号、联系人邮箱、网站、版权、开源协议等等信息，但与上面几条不同的是这些信息不是通过注解配置，而是通过创建一个 ApiInfo 对象，并且使用 Docket.appInfo() 方法来设置，我们在 SwaggerConfig.java 类中新增如下内容即可。

@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any())
            .build()
            .apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfo(
            "Spring Boot 项目集成 Swagger 实例文档",
            "我的博客网站：https://itweknow.cn，欢迎大家访问。",
            "API V1.0",
            "Terms of service",
            new Contact("名字想好没", "https://itweknow.cn", "gancy.programmer@gmail.com"),
                "Apache", "http://www.apache.org/", Collections.emptyList());
}

经过上面的步骤，我们的文档将会变成下图的样子，现在看起来就清楚很多了。

4.2 接口过滤

有些时候我们并不是希望所有的 Rest API 都呈现在文档上，这种情况下 Swagger2 提供给我们了两种方式配置，一种是基于 @ApiIgnore 注解，另一种是在 Docket 上增加筛选。

1.@ApiIgnore 注解。

如果想在文档中屏蔽掉删除用户的接口（user/delete），那么只需要在删除用户的方法上加上 @ApiIgnore 即可。

@ApiIgnore
public boolean delete(@PathVariable("id") int id)

2.在 Docket 上增加筛选。Docket 类提供了 apis() 和 paths() 两个方法来帮助我们在不同级别上过滤接口：

• apis() ：这种方式我们可以通过指定包名的方式，让 Swagger 只去某些包下面扫描。
• paths() ：这种方式可以通过筛选 API 的 url 来进行过滤。

在集成 Swagger2 的章节中我们这两个方法指定的都是扫描所有，没有指定任何过滤条件。如果我们在我们修改之前定义的 Docket 对象的 apis() 方法和 paths() 方法为下面的内容，那么接口文档将只会展示 /user/add 和 /user/find/{id} 两个接口。

.apis(RequestHandlerSelectors.basePackage("cn.itweknow.sbswagger.controller"))
.paths(Predicates.or(PathSelectors.ant("/user/add"),
        PathSelectors.ant("/user/find/*")))

4.3 自定义响应消息

Swagger 允许我们通过 Docket 的 globalResponseMessage() 方法全局覆盖 HTTP 方法的响应消息，但是首先我们得通过 Docket 的 useDefaultResponseMessages 方法告诉 Swagger 不使用默认的 HTTP 响应消息，假设我们现在需要覆盖所有 GET 方法的 500 和 403 错误的响应消息，我们只需要在 SwaggerConfig.java 类中的 Docket Bean 下添加如下内容：

.useDefaultResponseMessages(false)
.globalResponseMessage(RequestMethod.GET, newArrayList(
new ResponseMessageBuilder()
              .code(500)
              .message("服务器发生异常")
              .responseModel(new ModelRef("Error"))
              .build(),
       new ResponseMessageBuilder()
              .code(403)
              .message("资源不可用")
              .build()
));

添加如上面的代码后，如下图所示，您会发现在 SwaggerUI 页面展示的所有 GET 类型请求的 403 以及 500 错误的响应消息都变成了我们自定义的内容。

5.Swagger UI 的使用

5.1 接口查看

SwaggerUI 会以列表的方式展示所有扫描到的接口，初始状态是收缩的，我们只需要点击展开就好，而且会在左边标识接口的请求方式（GET、POST、PUT、DELETE 等等）。

5.2 接口调用

如下图所示，点击接口展开后页面右上角的 Try it out 按钮后，页面会变成如图所示：

SwaggerUI 会给我们自动填充请求参数的数据结构，我们需要做的只是点击 Execute 即可发起调用

5.3 Model

如下图所示，SwaggerUI 会通过我们在实体上使用的 @ApiModel 注解以及 @ApiModelProperty 注解来自动补充实体以及其属性的描述和备注。

6.相关注解说明

在本章节中我将给出一些 Swagger 中常用的注解以及其常用的属性，并对其一一解释，方便您查看。

6.1 Controller 相关注解

@Api: 可设置对控制器的描述。

6.2 接口相关注解

1.@ApiOperation: 可设置对接口的描述。

2.@ApiIgnore: Swagger 文档不会显示拥有该注解的接口。

@ApiImplicitParams: 用于描述接口的非对象参数集。

@ApiImplicitParam: 用于描述接口的非对象参数，一般与 @ApiImplicitParams 组合使用。

表 3. @ApiImplicitParam 主要属性

6.3 Model 相关注解

@ApiModel: 可设置接口相关实体的描述。
@ApiModelProperty: 可设置实体属性的相关描述。

表 4. @ApiModelProperty 主要属性