springboot 项目集成swagger并配置请求头 swagger-bootstrap-ui 并配置访问密码

2.springboot 集成 swagger

2.1.引入 swagger 相关的jar包

2.2.编写配置文件 SwaggerConfig   WebConfiguration（有配置请求头）

2.3.访问 swagger   

2.4.异常及解决办法

2.5.最后的效果是这个样子的

3.springboot 集成 swagger-bootstrap-ui

3.1.引入jar包

3.2.修改配置

3.3.最后效果

3.4.swagger 常用注解

4.设置swagger访问密码

4.1导入security相关jar包

4.2在springboot配置文件里配置swagger的登录用户、密码和登录后跳转的页面

4.3.新建 SpringSecurityConfiguration 配置类

4.4.再访问就是下面这个样子(访问时加载可能会有点慢)  访问地址：http://ip:端口/doc.html

1.什么是 swagger?优势有哪些

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

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

Swagger 的优势

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

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

2.springboot 集成 swagger

2.1.引入 swagger 相关的jar包

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

2.2.编写配置文件 SwaggerConfig   WebConfiguration（有配置请求头）

@Configuration
@EnableSwagger2
@Profile({"dev", "test"}) //swagger配置到生产环境测试环境下环境
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //加了ApiOperation注解的类，才生成接口文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //包下的类，才生成接口文档
                .apis(RequestHandlerSelectors.basePackage("com.labour.controller"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(globalOperation());       // 主要关注点----每个接口调用都填写token
    }
    private List<Parameter> globalOperation(){
        //添加head参数配置start
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        /*配置请求头*/
        tokenPar.name("Authorization").description("token令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        pars.add(tokenPar.build());
        return pars;
    }
    // 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 页面标题1
                .title("xx系统接口文档")
                // 描述
                .description("xx系统接口文档").termsOfServiceUrl("http://localhost:8080/")
                // 创建人
                .contact(new Contact("xxxxx", "http://www.xxxxx.com/", ""))
                // 版本号
                .version("1.0.1").build();
    }
}
/**
*@Author: make mpy
*@Description: 来注册拦截器
*@Date: 2020/12/30 14:33
*/
@Configuration
public class WebConfiguration implements WebMvcConfigurer {

    /**登陆校验的拦截器注入*/
    @Autowired
    private SessionInterceptor sessionInterceptor;

    // 这个方法用来注册拦截器，我们自己写好的拦截器需要通过这里添加注册才能生效
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        //表示除了登陆与注册之外，因为登陆注册不需要登陆也可以访问
        registry.addPathPatterns("/**").excludePathPatterns("/login", "/register").excludePathPatterns("/swagger-ui.html") 
                .excludePathPatterns("/swagger-resources/**")
                .excludePathPatterns("/error")
                .excludePathPatterns("/webjars/**");
    }

    // 这个方法是用来配置静态资源的，比如html，js，css，等等
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

2.3.访问 swagger   

ip:端口/swagger-ui.html

2.4.异常及解决办法

        如果出现这个 Swagger For input string: ““  的异常，请访问 这个地址查看解决方法

2.5.最后的效果是这个样子的

3.springboot 集成 swagger-bootstrap-ui

3.1.引入jar包

    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>swagger-bootstrap-ui</artifactId>
        <version>1.9.6</version>
    </dependency>

3.2.修改配置

    将 WebConfiguration 里所有的 swagger-ui.html 改成 doc.html 就ok

3.3.最后效果

3.4.swagger 常用注解

        请访问 上篇文章

4.设置swagger访问密码

利用 security 对 swagger 进行密码登录限制

4.1导入security相关jar包

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

4.2在springboot配置文件里配置swagger的登录用户、密码和登录后跳转的页面

    swagger:
      path: /doc.html
      user: root
      pwd: 123456

4.3.新建 SpringSecurityConfiguration 配置类

@Configuration
@EnableWebSecurity
public class SpringSecurityConfiguration extends WebSecurityConfigurerAdapter {
    @Value("${swagger.user}")
    private String user;
    @Value("${swagger.pwd}")
    private String pwd;
    /**
     * 存放了Swagger需要加入Spring Security认证的URL
     */
    private static final String[] AUTH_LIST = {
            "/v2/api-docs",
            "/configuration/ui",
            "/swagger-resources/**",
            "/configuration/security",
            "swagger-ui.html",
            "/doc.html",
            "/webjars/**"
    };
    /**
     * 让Spring Security接管Swagger认证授权的核心是configure(HttpSecurity http)方法
     * @param auth
     * @throws Exception
     */
    @Override
    protected void configure(AuthenticationManagerBuilder auth) throws Exception {
        auth.inMemoryAuthentication()
                .passwordEncoder(passwordEncoder())
                .withUser(user)
                .password(passwordEncoder().encode(pwd))
                .roles("USER");
    }
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
                .antMatchers(AUTH_LIST)
                .authenticated()
                .and()
                .formLogin()
                .and()
                .httpBasic();
        http.csrf().disable()
                .authorizeRequests()
                .antMatchers("/**").permitAll()
                .anyRequest()
                .authenticated().and().httpBasic();
    }
    @Bean
    public PasswordEncoder passwordEncoder(){
        return new BCryptPasswordEncoder();
    }
}

4.4.再访问就是下面这个样子(访问时加载可能会有点慢)  访问地址： http://ip:端口/doc.html