springboot整合swagger(附带token)

为什么使用Swagger？

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

Swagger 的优势:

1.支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。

2.提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

使用Swagger

导入相应依赖

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

创建SwaggerConfig文件

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //swagger测试的controller路径
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build()
                //下面两行为header中的Authorization认证，如不需要可不添加
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }
    
    //在测试界面简单进行描述
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("APIs")
                .description("api接口文档")
                .version("1.0")
                .build();
    }

    private List<ApiKey> securitySchemes() {
        //设置请求头信息
        List<ApiKey> result = new ArrayList<>();
        ApiKey apiKey = new ApiKey("Authorization", "Authorization", "header");
        result.add(apiKey);
        return result;
    }

    private List<SecurityContext> securityContexts() {
        //设置需要登录认证的路径
        List<SecurityContext> result = new ArrayList<>();
        result.add(getContextByPath("/*/.*"));
        return result;
    }

    private SecurityContext getContextByPath(String pathRegex){
        return SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.regex(pathRegex))
                .build();
    }

    //设置为全局调用，在测试界面输入一个Authorization值，后面测试的接口都将添加Authorization
    private List<SecurityReference> defaultAuth() {
        List<SecurityReference> result = new ArrayList<>();
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        result.add(new SecurityReference("Authorization", authorizationScopes));
        return result;
    }
}

使用Swagger进行接口测试

创建测试接口

@RestController
@Api(tags = "测试")
@RequestMapping("/test")
public class TestController {

    @GetMapping("/testSwagger")
    @ApiOperation(value = "swagger测试")
    public String swagger(){
        return "hello, swagger!";
    }

    @GetMapping("/testToken")
    @ApiOperation(value = "swagger中token测试")
    public String token(HttpServletRequest httpServletRequest){
        //返回请求头中Authorization的值
        if(httpServletRequest.getHeader("Authorization") == null){
            return "Authorization is null";
        }
        return httpServletRequest.getHeader("Authorization");
    }
}

默认的测试路径为：本机ip地址:port/swagger-ui.html
如 http://localhost:8080/swagger-ui.html

测试第一个接口

返回”hello, swagger!“
测试成功

测试第二个接口

当没有添加Authorization值时

返回”Authorization is null“

当添加Authorization值时

返回填入的Authorization对应值