Spring Boot整合swagger2

在上一篇中我们围绕了Spring Boot 集成了RESTful API项目，但是我们在实际开发中，我们的一个RESTful API有可能就要服务多个不同的开发人员或者开发团队，包括不限于PC,安卓，IOS，甚至现在的鸿蒙OS，web开发等等。为了减少与其他团队平时开发期间的频繁沟通成本，我们一般会选择创建一个相关的文档来记录所有的接口细节，也就是我们常常在实际开发中的接口文档。

但是我们采用接口文档进行记录的时候，发现，由于接口众多，并且他们的细节比较复杂，需要我们考虑不同场景的HTTP请求，甚至HTTP的相关头部信息，内容等，并且我们在创建这样的接口文档的时候，费时费力，很多的时候，我们都统计不全，甚至还会出现错误，这是因为人力统计的时候很容易出现差错，这也很正常。
并且随着时间的增加，我们对系统进行改动，不免也会对相关接口进行改动，这个只要是做过开发的都知道，这里调接口，那里调接口，我们就需要对文档进行修改，但是我们在开发过程中，发现代码和文档处于两个阶级，除非老大有严格的管控，不然就会造成很多问题。

这个时候，我们发现刚好有一种技术可以解决我们的问题，也就是Swagger2,他可以轻松的整合到Spring Boot中，并于Spring MVC 程序配合组织处很强大哦的RESTful API文档，极大的减少了我们创建文档的工作量，同时进一步将内容整合到我们的实现代码中，让代码修改和文档维护成为一体，同时修改，同时记录，让我们在修改代码的同时也修改了文档说明。

此外Swagger2 提供了强大的页面测试功能来调试每个RESTful API。具体效果如下图所示。

准备工作

我们需要有一个Spring Boot 实现的RESTful API工程，我们在上一篇就以及涉及到了，如果你没有接触过RESTful API,欢迎参照上一篇一起食用更佳。

Spring Boot整合Swagger 2

第一步，添加依赖，老样子，这里就不在详细描述了，如下：

xml 复制代码

<dependencies>
    <!-- Spring Boot Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Springfox Swagger2 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version> <!-- 请使用最新版本 -->
    </dependency>

    <!-- Springfox Swagger UI -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version> <!-- 请使用最新版本 -->
    </dependency>
</dependencies>

第二步：在Spring Boot的启动类中添加一个@EnableSwagger2Doc 注解，如下：

java 复制代码

@EnableSwagger2Doc
@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

第三步创建一个User实体对象,并给相关实体添加Swagger2 自带的接口，@ApiModel添加到实体类上，@ApiModelProperty添加到具体的属性之上，用于描述具体属性

java 复制代码

@ApiModel(description="用户实体")
public class User {

    @ApiModelProperty("用户编号")
    private Long id;
    @ApiModelProperty("用户姓名")
    private String name;
    @ApiModelProperty("用户年龄")
    private Integer age;

    public Long getId() {
        return id;
    }

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

    public String getName() {
        return name;
    }

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

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }
}

第四步，我们在application.properties文件上配置有关Swagger2的相关属性。

properties 复制代码

swagger.title=spring-boot-starter-swagger
swagger.description=Starter for swagger 2.x
swagger.version=1.9.0.RELEASE
swagger.license=Apache License, Version 2.0
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger
swagger.contact.name=miaow
swagger.contact.url=https://luoxiaohei520.github.io
swagger.contact.email=miaow@qq.com
swagger.base-package=com.miaow
swagger.base-path=/**

其中参数的相关含义如下：

swagger.title ：标题
swagger.description ：描述
swagger.version ：版本
swagger.license ：许可证
swagger.licenseUrl ：许可证URL
swagger.termsOfServiceUrl ：服务条款URL
swagger.contact.name ：维护人
swagger.contact.url ：维护人URL
swagger.contact.email ：维护人email
swagger.base-package ：swagger扫描的基础包，默认：全扫描
swagger.base-path：需要处理的基础URL规则，默认：/**

更多配置请参照官方文档

此时启动项目，访问链接： http://localhost:8080/swagger-ui.html

发现页面全是英文的。

第五步，我们来对Controller层的相关对象和方法进行API注解说明，在第四步我们发现通过浏览器访问，整个界面都是英文或者遵循代码定义的名称产生的，对用户并不友好，于是我们通过相关注解来给API增加说明：@Api，@ApiOperation注解来给API增加说明、通过@ApiImplicitParam、@ApiModel、@ApiModelProperty注解来给参数增加说明。

java 复制代码

@Api(tags = "用户管理")
@RestController
@RequestMapping(value = "/users")     // 通过这里配置使下面的映射都在/users下
public class UserController {

    // 创建线程安全的Map，模拟users信息的存储
    static Map<Long, User> users = Collections.synchronizedMap(new HashMap<>());

    @GetMapping("/")
    @ApiOperation(value = "获取用户列表")
    public List<User> getUserList() {
        List<User> r = new ArrayList<>(users.values());
        return r;
    }

    @PostMapping("/")
    @ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
    public String postUser(@RequestBody User user) {
        users.put(user.getId(), user);
        return "success";
    }

    @GetMapping("/{id}")
    @ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")
    public User getUser(@PathVariable Long id) {
        return users.get(id);
    }

    @PutMapping("/{id}")
    @ApiImplicitParam(paramType = "path", dataType = "Long", name = "id", value = "用户编号", required = true, example = "1")
    @ApiOperation(value = "更新用户详细信息", notes = "根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
    public String putUser(@PathVariable Long id, @RequestBody User user) {
        User u = users.get(id);
        u.setName(user.getName());
        u.setAge(user.getAge());
        users.put(id, u);
        return "success";
    }

    @DeleteMapping("/{id}")
    @ApiOperation(value = "删除用户", notes = "根据url的id来指定删除对象")
    public String deleteUser(@PathVariable Long id) {
        users.remove(id);
        return "success";
    }
}

之后再通过：http://localhost:8080/swagger-ui.html 访问，点击相关信息，可以看到具体的参数和相关属性。

还可以相关提示进行测试：

在上图请求的页面中，我们看到user的Value是个输入框，是的，Swagger除了查看接口功能外，还提供了调试测试功能，我们可以点击上图中右侧的Model Schema（黄色区域：它指明了User的数据结构），此时Value中就有了user对象的模板，我们只需要稍适修改，点击下方"Try it out！"按钮，即可完成了一次请求调用！

此时，你也可以通过几个GET请求来验证之前的POST请求是否正确。