前前言

spring security Oauth2 和 swagger2 是什么呢？简单介绍一下，但是如果不明白的话不适合看这个文章。

spring security Oauth2
一个很好用的安全框架，可以很轻松的实现细粒度的接口防护
swagger2
这是一个动态生成 api 文档的东西，有了这个东西妈妈再也不用担心一边维护代码一边维护文档了。

前言

spring security Oauth2 的使用在我的其他博客中也讲到了，这里就不在叙述。这篇文章主要讲述的就是我们的应用已经被 spring security Oauth2 保护的情况下，集成 swagger2 生成api文档。

大概实现步骤

引入 pom 依赖（假如你的项目是使用 Maven 管理，如果使用的不是 Maven 的话你知道该怎么做）
refresh 一下 pom （有的小朋友会遗忘）
新建一个 swagger2 的配置类
把 swagger2 使用的接口放行（被 Oauth2 拦了还玩个毛线）

具体编码实现

pom依赖

<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>

这里注意我使用的是2.8.0版本，为什么是这个版本呢？我试了2.9.x，也试了2.7.x，有一些问题只有2.8.0解决了，例如“接口返回示例”部分只有2.8.0按照Java类书写的顺序显示，其他版本是按照字符串顺序显示。其他问题我就不一一列举了，大家尝试一下，也没必要一定使用2.8.0。更换版本的话只需要改一下 pom 里面的版本即可，其他配置不用变。jsonview 组件截止鄙人写博客的时候 swagger2 都没有支持

新建 swagger2 配置类

package com.ybk.ordering.config;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.OAuthBuilder;
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.Arrays;
import java.util.Collections;
//把import写进来主要是为了确保万无一失

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //这个东西是项目的根路径，也就是“/oauth/token”前面的那一串
    //这个东西在配置文件里写的，大家也可以直接写死在配置文件中
    @Value("${auth_server}")
    private String AUTH_SERVER;

    /**
     * 主要是这个方法，其他的方法是抽出去的，所以大家不要害怕为啥有这么多方法
     * 在 basePackage 里面写需要生成文档的 controller 路径
     */
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ybk.ordering.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo())
                .securitySchemes(Collections.singletonList(securityScheme()))
                .securityContexts(Collections.singletonList(securityContext()));
    }

    /**
     * 这个方法主要是写一些文档的描述
     */
    private ApiInfo apiInfo() {
        return new ApiInfo(
                "某某系统API",
                "This is a very pretty document!",
                "1.0",
                "",
                new Contact("师父领进门", "", "qixiazhen@qq.com"),
                "", "", Collections.emptyList());
    }

    /**
     * 这个类决定了你使用哪种认证方式，我这里使用密码模式
     * 其他方式自己摸索一下，完全莫问题啊
     */
    private SecurityScheme securityScheme() {
        GrantType grantType = new ResourceOwnerPasswordCredentialsGrant(AUTH_SERVER + "/oauth/token");

        return new OAuthBuilder()
                .name("spring_oauth")
                .grantTypes(Collections.singletonList(grantType))
                .scopes(Arrays.asList(scopes()))
                .build();
    }

    /**
     * 这里设置 swagger2 认证的安全上下文
     */
    private SecurityContext securityContext() {
        return SecurityContext.builder()
                              .securityReferences(Collections.singletonList(new SecurityReference("spring_oauth", scopes())))
                              .forPaths(PathSelectors.any())
                              .build();
    }

    /**
     * 这里是写允许认证的scope
     */
    private AuthorizationScope[] scopes() {
        return new AuthorizationScope[]{
                new AuthorizationScope("all", "All scope is trusted!")
        };
    }

}

大体上就些配置，如果有哪些方法调用我没说明白或者没法儿理解的话用 IDE 进去看看源码的注释基本也就明白了。

Oauth2 放行 swagger2

@Configuration
@EnableResourceServer
public class ResourceServerConfig extends ResourceServerConfigurerAdapter {

    @Override
    public void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
            .antMatchers(
                    "/webjars/**",
                    "/resources/**",
                    "/swagger-ui.html",
                    "/swagger-resources/**",
                    "/v2/api-docs")
            .permitAll();
    }
}

如你所见，配置写在资源服务器里面。这里是简化的代码，实际使用中你在原有配置的基础上把我上面写的这些路径放行即可。