SpringBoot+Security+Swagger2配置

SpringBoot+Security+Swagger2配置

前言：本来想用Swagger3呢，但是找了好久都没有找到Swagger3的文档，百度也搜不到。这里说的是添加security的登录、登出配置。所以就借用了网上的部分代码做的

1. 首先在pom.xml中添加swagger2的坐标

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
    <!--移除swagger-models 1.5.20 依赖，存在Swagger2异常:Illegal DefaultValue null for parameter type integer问题-->
    <exclusions>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
        </exclusion>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>1.5.21</version>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-models</artifactId>
    <version>1.5.21</version>
</dependency>

2. 创建一个swagger的配置文件

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * Swagger2Config 配置文件
 */
@Configuration
public class Swagger2Config implements WebMvcConfigurer {
    /**
     * 导入配置文件中的值
     */
    @Value("${debugger_tools}")
    private Boolean debuggerTools;
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例，用来控制那些借口暴露给Swagger来展现
     * 本例采用指定扫描的包路径来定义指定要建立API的目录
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
        		// 这里表示是否启用swagger
                .enable(debuggerTools)
                // 项目前缀
                .apiInfo(new ApiInfoBuilder()
                        .title("*******")//网页标题
                        .description("一个简单的测试")//网页描述
                        .contact(new Contact("tom",null,"tom@163.com"))//用户名，url,email
                        .version("1.00")//接口版本号
                        .build());
    }

}

3. 在security中configure配置，其他配置这里不介绍

/**
 * 拦截请求后的权限设置
 *
 * @param http
 * @throws Exception
 */
@Override
protected void configure(HttpSecurity http) throws Exception {
    http.authorizeRequests()
            // 设置Swagger2匿名访问
            .antMatchers("/swagger-ui.html", "/webjars/**",
                    "/v2/**", "/swagger-resources/**").permitAll()
}

4. 实现以上两步，即可通过http://IP:端口/项目前缀/swagger-ui.html访问swagger，项目前缀有则写没有则不写；例如http://localhost:8080/swagger-ui.html
5. 细心的朋友会发现：因为Security是自带登录、登出请求的，因此swagger并不会生成这两个请求，因此需要手动去增加这两个请求。也就是这里swagger3中我尚未找到解决办法。在swagger3中这里使用的方法很多都弃用了，也没找到官方文档去解决这个问题。说再多都是废话，最终实现才是目的，因此使用Swagger2，上代码：

import com.fasterxml.classmate.TypeResolver;
import org.springframework.http.HttpMethod;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Component;
import springfox.documentation.builders.OperationBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiDescription;
import springfox.documentation.service.Operation;
import springfox.documentation.service.Parameter;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.ApiListingScannerPlugin;
import springfox.documentation.spi.service.contexts.DocumentationContext;
import springfox.documentation.spring.web.readers.operation.CachingOperationNameGenerator;

import java.util.*;

/**
 * 手动添加swagger接口，如登录接口、登录出接口等
 *
 * @author songyinyin
 * @date 2020/6/17 下午 10:03
 */
@Component
public class SwaggerAddtion implements ApiListingScannerPlugin {
    /**
     * Implement this method to manually add ApiDescriptions
     * 实现此方法可手动添加ApiDescriptions
     *
     * @param context - Documentation context that can be used infer documentation context
     * @return List of {@link ApiDescription}
     * @see ApiDescription
     */
    @Override
    public List<ApiDescription> apply(DocumentationContext context) {
        return Arrays.asList(login(),unLogin());
    }
    /**
     * 定义用户名的字段
     * @return
     */
    public Parameter username(){
        return new ParameterBuilder()
                .description("用户名")
                .type(new TypeResolver().resolve(String.class))
                .name("username")
                .parameterType("form")
                .parameterAccess("access")
                .defaultValue("admin")
                .required(true)
                .modelRef(new ModelRef("string"))
                .build();
    }

    /**
     * 定义密码的字段
     * @return
     */
    public Parameter password(){
        return new ParameterBuilder()
                .description("密码")
                .type(new TypeResolver().resolve(String.class))
                .name("password")
                .parameterType("form")
                .parameterAccess("access")
                .defaultValue("admin123")
                .required(true)
                .modelRef(new ModelRef("string"))
                .build();
    }
    /**
     * 定义验证码的字段
     */
    public Parameter code(){
        return new ParameterBuilder()
                .description("验证码")
                .type(new TypeResolver().resolve(String.class))
                .name("code")
                .parameterType("form")
                .parameterAccess("access")
                .required(false)
                .modelRef(new ModelRef("string"))
                .build();
    }
    /**
     * 定义返回消息
     * @return
     */
    public Set<ResponseMessage> responseMessages(){
        Set<ResponseMessage> messages = new HashSet<>();
        messages.add(new ResponseMessageBuilder().code(200).message("ok").build());
        messages.add(new ResponseMessageBuilder().code(401).message("Unauthorized").build());
        messages.add(new ResponseMessageBuilder().code(403).message("Forbidden").build());
        messages.add(new ResponseMessageBuilder().code(404).message("Not Found").build());
        return messages;
    }

    /**
     * 登录请求
     * @return
     */
    public ApiDescription login(){
        Operation loginOperation = new OperationBuilder(new CachingOperationNameGenerator())
                .tags(Collections.singleton("用户接口"))
                .summary("登录")
                .notes("登录")
                .method(HttpMethod.POST)
                .consumes(Collections.singleton(MediaType.APPLICATION_FORM_URLENCODED_VALUE)) // 接收参数格式
                .produces(Collections.singleton(MediaType.APPLICATION_JSON_VALUE)) // 返回参数格式
                .parameters(Arrays.asList(username(),password(),code())) //定义参数
                .responseMessages(responseMessages())
                .build();

        ApiDescription loginApiDescription = new ApiDescription("login", "/login","登录接口",
                Arrays.asList(loginOperation), false);
        return loginApiDescription;
    }
    /**
     * 退出登录请求
     * @return
     */
    public ApiDescription unLogin(){
        Operation unLoginOperation = new OperationBuilder(new CachingOperationNameGenerator())
                .tags(Collections.singleton("用户接口"))
                .summary("登出")
                .notes("登出")
                .method(HttpMethod.GET)
                .produces(Collections.singleton(MediaType.APPLICATION_JSON_VALUE)) // 返回参数格式
                .responseMessages(responseMessages())
                .build();
        ApiDescription unLoginApiDescription = new ApiDescription("logout", "/logout","退出登录接口",
                Arrays.asList(unLoginOperation), false);
        return unLoginApiDescription;
    }
    /**
     * 是否使用此插件
     *
     * @param documentationType swagger文档类型
     * @return true 启用
     */
    @Override
    public boolean supports(DocumentationType documentationType) {
        return DocumentationType.SWAGGER_2.equals(documentationType);
    }
}

7. 在第二步中有一个属性是debuggerTools，说是导入配置文件中的值，是的，正式中swagger是为了方便调试用的，所以在生产环境中是无需启用，因此可以使用配置文件来控制是否启用swagger。可以在不同的环境变量中定义debugger_tools属性值。根据启用不同环境配置，来决定是否启用swagger(SpringBoot如何配置多环境)
   如下：

# 是否启用swagger,postman调试
# application-dev.yml环境
debugger_tools: true


# application-test.yml、application-prod.yml环境
debugger_tools: false

8. 结果，因为我的登录、登出路径是重定义加了/user 。默认没有
   

参考文章：
Security如何配置swagger2
swagger2添加Security登录接口