Spring Boot 集成 Swagger 在线接口文档

认识Swagger

Swagger解决的问题

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了前后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。前端和后端的唯一联系变成了 API 接口，所以 API 文档变成了前后端开发人员联系的纽带，变得越来越重要。随着代码的不断更新，开发人员在开发新的接口或者更新旧的接口后，由于开发任务的繁重，往往文档很难持续跟着更新，Swagger 就是用来解决该问题的一款重要的工具，对使用接口的人来说，开发人员不需要给他们提供文档，只要告诉一个 Swagger 地址，即可展示在线的 API 接口文档，除此之外，调用接口的人员还可以在线测试接口数据，同样地，开发人员在开发接口时，同样也可以利用 Swagger 在线接口文档测试接口数据，这给开发人员提供了便利。

Swagge的使用

1.导入Swagge的依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
</dependency>

2.Swagger 配置

Swagger 的配置

类上除了添加必要的@Configuration 注解外，还需要添加@EnableOpenApi 注解。

@Configuration：注释类表明其主要目的是作为bean定义的源。

@EnableOpenApi：在用到swagger3.0版本的时候就可以用到这个注解了，可以放在启动类上或者是swagger的配置文件上。

application.properties中的配置：

spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

3.启动项目

在浏览器中输入 http://localhost:8080/test/swagger-ui/，即可看到 swagger 的接口页面，说明 Swagger 集成成功。对照 Swagger 配置文件中的配置，可以很明确的知道配置类中每个方法的作用。有时候可能会出现在配置 Swagger 时关不掉，是因为浏览器缓存引起的，清空一下浏览器缓存即可解决问题。

实体类注解

@ApiModel 和@ApiModelProperty 注解。

    @ApiModel(value = "用户实体类")
    public class User {
        @ApiModelProperty(value = "用户唯一标识")
        private Long id;
        @ApiModelProperty(value = "用户姓名")
        private String username;
        @ApiModelProperty(value = "用户密码")
        private String password;
    }

@ApiModel 注解用于实体类，表示对类进行说明，用于参数用实体类接收。

@ApiModelProperty 注解用于类中属性，表示对 model 属性的说明或者数据操作更改。

Controller 类中相关注解

    @RestController
    @RequestMapping("/swagger")
    @Api(value = "Swagger2 在线接口文档")
    public class TestController {
        @GetMapping("/get/{id}")
        @ApiOperation(value = "根据用户唯一标识获取用户信息")
        public JsonResult<User> getUserInfo(@PathVariable @ApiParam(value = "用户唯一标识") Long id) {
// 模拟数据库中根据 id 获取 User 信息
            User user = new User(id, "李四", "123456");
            return new JsonResult(user);
        }
    }

@Api 注解用于类上，表示标识这个类是 swagger 的资源。

@ApiOperation 注解用于方法，表示一个 http 请求的操作。

@ApiParam 注解用于参数上，用来标明参数信息。

Swagger的使用直接在页面返回了 json 格式的数据，开发人员可以直接使用该在线接口来测试数据的正确与否，比较方便。