springboot 2.1.0.RELEASE 项目加入swagger接口文档

Release v2.1.0.RELEASE · spring-projects/spring-boot · GitHub

springboot 2.1.0.RELEASE发行日期是2018年10月30日（Oct 30, 2018）

不要使用过高的swagger版本，如SpringFox Boot Starter » 3.0.0，否则报错：

spring-plugin-core-1.2.0.RELEASE.jar不兼容

2023-11-15 11:50:24.544 febs [main] ERROR o.s.b.d.LoggingFailureAnalysisReporter - 

***************************
APPLICATION FAILED TO START
***************************

Description:

An attempt was made to call the method org.springframework.plugin.core.PluginRegistry.getPluginFor(Ljava/lang/Object;)Ljava/util/Optional; but it does not exist. Its class, org.springframework.plugin.core.PluginRegistry, is available from the following locations:

    jar:file:/D:/env/maven/repo395/org/springframework/plugin/spring-plugin-core/1.2.0.RELEASE/spring-plugin-core-1.2.0.RELEASE.jar!/org/springframework/plugin/core/PluginRegistry.class

It was loaded from the following location:

    file:/D:/env/maven/repo395/org/springframework/plugin/spring-plugin-core/1.2.0.RELEASE/spring-plugin-core-1.2.0.RELEASE.jar


Action:

Correct the classpath of your application so that it contains a single, compatible version of org.springframework.plugin.core.PluginRegistry

这个错误涉及版本依赖兼容性，研究明白所需时间成本不划算。

改用同时期的swagger版本即可。

具体配置方法：

1、在pom.xml中加入依赖

        <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、在代码中加入配置类：

package cc.mrbird.febs.common.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;
@Configuration  
@EnableSwagger2
public class Swagger2Configuration {
   //api接口包扫描路径
   public static final String SWAGGER_SCAN_BASE_PACKAGE = "cc.mrbird.febs";
   public static final String VERSION = "1.0.0";
   @Bean
   public Docket createRestApi() {
       return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .select()
                   .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                   .paths(PathSelectors.any()) // 可以根据url路径设置哪些请求加入文档，忽略哪些请求
                   .build();
   }
   private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
                   .title("食堂库房管理系统API") //设置文档的标题
                   .description("系统后台接口swagger说明文档") // 设置文档的描述
                   .version(VERSION) // 设置文档的版本信息-> 1.0.0 Version information
                   .termsOfServiceUrl("www.jlrc.com") // 设置文档的License信息->1.3 License information
                   .build();
   }
}

类的注释不可缺失：

@Configuration  
@EnableSwagger2

所填内容与界面上的标题信息显示是一一对应的

实际上就是向spring物流中心存入了Docket类型的Bean对象备用（向spring容器存入了Docket类型的Bean）

3、由于项目使用了shiro做鉴权访问控制，需要开放swagger访问路径

Shiro 放行Swagger_shiro 放行 swagger-CSDN博客

// 放行Swagger相关访问
filterChainDefinitionMap.put("/docs", "anon");
filterChainDefinitionMap.put("/swagger-ui.html", "anon");
filterChainDefinitionMap.put("/webjars/springfox-swagger-ui/**", "anon");
filterChainDefinitionMap.put("/swagger-resources/**", "anon");
filterChainDefinitionMap.put("/v2/api-docs", "anon");

package cc.mrbird.febs.common.authentication;

import org.apache.shiro.mgt.SecurityManager;
import org.apache.shiro.spring.security.interceptor.AuthorizationAttributeSourceAdvisor;
import org.apache.shiro.spring.web.ShiroFilterFactoryBean;
import org.apache.shiro.web.mgt.DefaultWebSecurityManager;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import javax.servlet.Filter;
import java.util.LinkedHashMap;

/**
 * Shiro 配置类
 *
 * @author MrBird
 */
@Configuration
public class ShiroConfig {

    @Bean
    public ShiroFilterFactoryBean shiroFilterFactoryBean(SecurityManager securityManager) {
        ShiroFilterFactoryBean shiroFilterFactoryBean = new ShiroFilterFactoryBean();
        // 设置 securityManager
        shiroFilterFactoryBean.setSecurityManager(securityManager);

        // 在 Shiro过滤器链上加入 JWTFilter
        LinkedHashMap<String, Filter> filters = new LinkedHashMap<>();
        filters.put("jwt", new JWTFilter());
        shiroFilterFactoryBean.setFilters(filters);

        LinkedHashMap<String, String> filterChainDefinitionMap = new LinkedHashMap<>();

        // swagger接口文档
        // 放行Swagger相关访问
        filterChainDefinitionMap.put("/docs", "anon");
        filterChainDefinitionMap.put("/swagger-ui.html", "anon");
        filterChainDefinitionMap.put("/webjars/springfox-swagger-ui/**", "anon");
        filterChainDefinitionMap.put("/swagger-resources/**", "anon");
        filterChainDefinitionMap.put("/v2/api-docs", "anon");

        // 所有请求都要经过 jwt过滤器
        filterChainDefinitionMap.put("/**", "jwt");

        shiroFilterFactoryBean.setFilterChainDefinitionMap(filterChainDefinitionMap);
        return shiroFilterFactoryBean;
    }

    @Bean
    public SecurityManager securityManager() {
        DefaultWebSecurityManager securityManager = new DefaultWebSecurityManager();
        // 配置 SecurityManager，并注入 shiroRealm
        securityManager.setRealm(shiroRealm());
        return securityManager;
    }

    @Bean
    public ShiroRealm shiroRealm() {
        // 配置 Realm
        return new ShiroRealm();
    }

    @Bean
    public AuthorizationAttributeSourceAdvisor authorizationAttributeSourceAdvisor(SecurityManager securityManager) {
        AuthorizationAttributeSourceAdvisor authorizationAttributeSourceAdvisor = new AuthorizationAttributeSourceAdvisor();
        authorizationAttributeSourceAdvisor.setSecurityManager(securityManager);
        return authorizationAttributeSourceAdvisor;
    }
}

4、swagger-ui.html 404问题

访问

http://localhost:9527/swagger-ui.html

提示404找不到页面

原因是自定义的webmvc配置类的addResourceHandlers方法（@override父类接口的WebMvcConfigurer#addResourceHandlers）未将io.springfox:springfox-swagger-ui:2.9.2包中的resource资源引入spring项目中，需要手动配置

cc.mrbird.febs.common.config.MyWebMvcConfigurerAdapter#addResourceHandlers

package cc.mrbird.febs.common.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
//@EnableWebMvc 不要加@EnableWebMvc，加了会启用Spring MVC框架的默认配置，导致获取RequestContextHolder.getRequestAttributes()为空
public class MyWebMvcConfigurerAdapter implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {

        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
       
      //registry.addResourceHandler("/imagesWeb/**").addResourceLocations("file:E:/Project/食堂采购系统/db/");// 这个路径有疑问，不能直接操作E盘
        WebMvcConfigurer.super.addResourceHandlers(registry);
    }
}

https://www.cnblogs.com/birdy-silhouette/p/16400888.html

RequestContextHolder.getRequestAttributes()空指针-CSDN博客

@EnableWebMvc注解的作用和示例 – 编程技术之美-IT之美

至此，启动项目后可以正常访问swagger页面。

参考：

https://www.cnblogs.com/xiaoqi/p/swagger-ui-404.html

https://www.cnblogs.com/pangguoming/p/10551895.html

https://mvnrepository.com/artifact/io.springfox/springfox-swagger2

Swagger-3：配置扫描接口及开关_哔哩哔哩_bilibili

https://www.cnblogs.com/progor/p/13297904.html

PS：swagger有个官网：

API Documentation & Design Tools for Teams | Swagger

虽然也能找到swagger ui的介绍，但是内容完全与springboot集成无关