十三、springboot整合swagger2

前言

​ 在上一篇文章springboot构建restful风格接口基础上，整合swagger，接口文档并添加全局验证参数token。

​ swagger简介

Swagger是一款RESTful接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务，加上swagger-ui，可以有很好的呈现。

当我们在后台的接口修改了后，swagger可以实现自动的更新，而不需要人为的维护这个接口进行测试。

一、pom文件引入依赖

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!--swagger 依赖包-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>

二、新建swagger配置文件

import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

@Configuration
@EnableSwagger2
//是否开启swagger，正式环境一般是需要关闭的（避免不必要的漏洞暴露！），可根据springboot的多环境配置进行设置
@ConditionalOnProperty(name = "swagger.enable",  havingValue = "true")
public class Swagger2Config {
    private String keyName= "token";
    // swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
    @Bean
    public Docket createApiUser() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("用户模块")
                .apiInfo(apiInfo())
                .select()
                // 为当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.yuan.restful.user.controller")).paths(PathSelectors.any())
                .build()
                // （securitySchemes与securityContexts作用为配置全局token参数）
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }
    // 构建 api文档的详细信息函数（配置一些网站标题，版本号，作者等信息）
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 页面标题
                .title("Spring Boot 测试使用 Swagger2 构建RESTful API")
                //条款信息
                .termsOfServiceUrl("http://www.baidu.com")
                // 创建人信息
                .contact(new Contact("张三",  "http://www.baidu.com",  "zhangsan@qq.com"))
                // 版本号
                .version("1.0")
                // 描述
                .description("API 描述")
                .build();
    }

    private List<ApiKey> securitySchemes() {
        List<ApiKey> apiKeyList = new ArrayList();
        //注意，这里应对应登录token鉴权对应的k-v
        apiKeyList.add(new ApiKey("签名token", keyName, "header"));
        return apiKeyList;
    }

    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .forPaths(PathSelectors.regex("^(?!auth).*$"))
                        .build());
        return securityContexts;
    }

    List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference(keyName, authorizationScopes));
        return securityReferences;
    }
}

这里要注意的是springboot 配置文件以及需要使用注解的java文件必须要在Application.java下或者同级，不然无法识别
类似如下：即可

三、在接口上加上swagger相关注解

import com.yuan.restful.user.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

import java.util.*;

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

    // 创建线程安全的Map
    static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());

    // @RequestMapping(value="/", method=RequestMethod.GET)
    @GetMapping("/")
    @ApiOperation(value = "用户列表", notes = "备注")
    public List<User> getUserList() {
        // 处理"/users/"的GET请求，用来获取用户列表
        // 还可以通过@RequestParam从页面中传递参数来进行查询条件或者翻页信息的传递
        List<User> r = new ArrayList<User>(users.values());
        return r;
    }

    //@RequestMapping(value="/", method=RequestMethod.POST)
    @PostMapping("/")
    @ApiOperation(value = "保存用户")
    public String postUser(@ModelAttribute User user) {
        // 处理"/users/"的POST请求，用来创建User
        // 除了@ModelAttribute绑定参数之外，还可以通过@RequestParam从页面中传递参数
        users.put(user.getId(), user);
        return "success";
    }

    //@RequestMapping(value="/{id}", method=RequestMethod.GET)
    @GetMapping("/{id}")
    @ApiOperation(value = "查询单个用户")
    public User getUser(@PathVariable Long id) {
        // 处理"/users/{id}"的GET请求，用来获取url中id值的User信息
        // url中的id可通过@PathVariable绑定到函数的参数中
        return users.get(id);
    }

    //@RequestMapping(value="/{id}", method=RequestMethod.PUT)
    @PutMapping("/{id}")
    @ApiOperation(value = "修改用户")
    public String putUser(@PathVariable Long id, @ModelAttribute User user) {
        // 处理"/users/{id}"的PUT请求，用来更新User信息
        User u = users.get(id);
        u.setName(user.getName());
        u.setAge(user.getAge());
        users.put(id, u);
        return "success";
    }

    //@RequestMapping(value="/{id}", method=RequestMethod.DELETE)
    @DeleteMapping("/{id}")
    @ApiOperation(value = "删除用户")
    public String deleteUser(@PathVariable Long id) {
        // 处理"/users/{id}"的DELETE请求，用来删除User
        users.remove(id);
        return "success";
    }

}

四、在实体类上加上swagger注解

import com.yuan.restful.user.enu.Status;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value = "用户对象")
public class User {
    private Long id;
    @ApiModelProperty(value = "姓名")
    private String name;
    @ApiModelProperty(value = "年龄")
    private Integer age;
    @ApiModelProperty(value = "状态")
    private Status status;

    // 省略setter和getter
}

五、验证swagger效果

启动项目打开地址http://localhost:8080/swagger-ui.html，就看得到如下界面。

图标1，就是配置全局参数token，图标2，就是apiInfo配置相关信息