比swagger稍稍完善的接口展现工具knife4j使用

背景

项目之前使用swagger用来做服务端的接口展现，我们知道swagger默认的页面比较粗糙，所以国人开发了一个更加便于使用的界面knife4j，吐槽下这个名字起的很拗口。

遇到的问题

在项目初期使用knife4j没出现什么问题，后来服务接入了网关，由于knife4j要加载静态资源，所以当时又在网关加了静态资源地址的过滤。但是最近又偶现无法登录和访问的情况，且出现了跨域的错误，而且每次都需要使用login才能登录，查看官方文档没有提到有login的说法，于是接手研究到底是怎么处理的。
通过查看代码，才知道是在knife4j上面加了一层spring security，然后配置的账号和密码，支持了HttpBasic和login页面的方式，但在网关模式的请求会有问题。
在研究官方文档以后，发现在2.0.1版本之后knife4j自己带了httpBasic权限控制，通过简单配置就可以使用，于是做了修改。下面把knife4j自带权限控制和基于spring security两种方式的实现代码都放出来，大家略作参考。

引入依赖

    
      com.github.xiaoymin
      knife4j-spring-boot-starter
      2.0.1

代码

使用spring security 的权限限制

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;

@Configuration
@EnableWebSecurity
public class SpringSecurityConfiguration extends WebSecurityConfigurerAdapter {
    private static final String[] AUTH_LIST = {"/v2/api-docs", "/configuration/ui", "/swagger-resources/**", "/configuration/security", "/swagger-ui.html", "/webjars/**"};

    @Override
    protected void configure(AuthenticationManagerBuilder auth) throws Exception {
        auth.inMemoryAuthentication()
                .passwordEncoder(passwordEncoder())
                .withUser("admin")
                .password(passwordEncoder().encode("admin"))
                .roles("USER");
        
        //账号密码配置
    }

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.csrf().disable().authorizeRequests() 
                .antMatchers("doc.html#**")
                .permitAll()
                .antMatchers(AUTH_LIST)
                .authenticated()
                .and()
                .formLogin()  //会有一个 跳转/login的默认登录页面
                .and()
                .httpBasic();  //HttpBasic登录
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }
}

knife4j 自带的httpBasic权限限制

application.yml 配置

## 开启Swagger的Basic认证功能,默认是false
knife4j:
  production: true  #对于线上maven profile禁止
  basic:
    enable: true
    username: admin
    password: admin
  cors: true

swagger 配置类

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * 验证方式HttpBasic
 * com.github.xiaoymin.knife4j.spring.filter.SecurityBasicAuthFilter#doFilter(javax.servlet.ServletRequest, javax.servlet.ServletResponse, javax.servlet.FilterChain)
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
@Profile({"develop"})
public class SwaggerConfiguration {

    @Bean
    public Docket allApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(userInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.company.xxx.xxxx"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo userInfo() {
        return new ApiInfoBuilder()
                .title("接口API 文档")
                .description("HTTP对外开放接口")
                .version("1.0.0")
                .termsOfServiceUrl("http://swagger.io")
                .license("LICENSE")
                .licenseUrl("http://swagger.io")
                .build();
    }
}

参考内容

knife4j文档权限控制
knife4j github