作为一个强迫症重度的程序猿 不想多导一个jar包

本文创作背景是鉴于网上大多数是旧版本swagger2的教程，且没有针对2和3区别描述，话不多说 直接步入正题。

导包正确方式

如果只需要knife4j文档 导这一个包就够了 这里以3.0+版本举例
(对springboot比较熟悉的同学应该清楚 starter目的就是将其它包并入一个包 旨在开箱即用 一个正确的stater 会把其它杂七杂八的包 都包含在里面)

		<!-- 如果只需要knife4j文档 导这一个包就够了 -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.3</version>
        </dependency>

如果还想同时使用swagger界面 那么需要额外加一个包:

        <!--可选，引入后，原/swagger-ui.html提供的页面仍可正常使用-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>3.0.0</version>
        </dependency>

如果不想用knife4j 只想用swagger 不需要上面的包 那么只需要下面这个包：

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

本文是基于security环境 security的jar包：

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-security</artifactId>
        </dependency>

swagger2在security中放行

在swagger2中，根据大部分教程 我们的放行姿势 是经典的四件套:

/webjars/**
/swagger-resources/**
/v2/**
/swagger-ui/**

代码示例如下：

@Configuration
public class SecuritySecureConfig extends WebSecurityConfigurerAdapter {

    /** WebSecurity 不走过滤链的放行  即不通过security 完全对外的/最大级别的放行 **/
    @Override
    public void configure(WebSecurity web) throws Exception {
          // test直接放行了  如果是login接口 必须通过HttpSecurity 走过滤链 因为登录涉及 SecurityContextHolder
        web.ignoring().antMatchers("/test/**");
    }

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        // 登录成功处理类
        SavedRequestAwareAuthenticationSuccessHandler successHandler = new SavedRequestAwareAuthenticationSuccessHandler();
        successHandler.setTargetUrlParameter("redirectTo");

        http.authorizeRequests()
                //静态文件允许访问
                .antMatchers("/assets/**").permitAll()
                .antMatchers("/webjars/**").permitAll()
                .antMatchers("/swagger-resources/**").permitAll()
                .antMatchers("/v2/**").permitAll()
                
                .antMatchers(  "/swagger-ui/**").permitAll()
                // 放行
                .antMatchers( "/login","css/**","/js/**","/image/*").permitAll()
                //其他所有请求需要登录, anyRequest 不能配置在 antMatchers 前面
                .anyRequest().authenticated()
                .and()
                //登录页面配置，用于替换security默认页面
//                .formLogin().loginPage(  "/login").successHandler(successHandler).and()
                //登出页面配置，用于替换security默认页面
//                .logout().logoutUrl( "/logout").and()
                .httpBasic();

    }
}

这段代码基本正确，但是有个隐患 : /v2/**
如果有同学遇到v2版本的开发， 且将接口以/v2开头 将造成严重后果
所以博主推荐 不要为了省事那么写 最好写全： /v2/api-docs

swagger3在security中放行

当某一天 我们版本迭代升级 更新到swagger3的时候，用上面配置 会发现swagger、knife都无法访问 这这这为什么呢？

下面提一下博主的分析思路：

knife4j放行失败原因分析：

其它配置未改变 只是starter版本升级 导致的放行失败 一般可以推测是两个原因：

1. security 机制改变 正确放行姿势 不再是

            http.authorizeRequests()
            .antMatchers("/xxx/**").permitAll()
   

   但是我们应该明白 swagger只是一个额外的文档工具 它不应该去改变security的机制 所以这点我们可以排除

2. 放行失败 说明url被拦截，url被拦截 那就意味着升级后 文档地址可能发生了改变

3. 所以我们可以先将security的jar包先去除，观察knife4j文档页面：
   

由此我们可知 需要新增一行放行代码：

      .antMatchers("/v3/api-docs").permitAll()

再将security包 重新加回项目中

swagger访问失败原因分析：

knife4j是因为url的变更 那swagger有没有也是这种可能呢?

我们之前(swagger2)的访问url是

localhost:8080/swagger-ui.html

这个地址是怎么来的呢?

html是在swagger-ui jar包中

那再看看swagger3中 它变成了什么：

没错 名字发生了改变，我们在swagger3中的正确访问url为：

localhost:8080/swagger-ui/index.html