springboot集成Swagger2在线生成Api文档遇到的坑

为做好的项目写个API文档，传统方式太麻烦和费时间，于是在网上看到了swagger2在线api生成，决定使用这个（swagger有两种不同的版本，一个是swagger，一个是springfox的swagger2，我使用的是swagger2）。在配置Swagger2的时候出现访问时界面空白的坑，刚开始以为是配置的swagger-ui版本不兼容，还有说是与Spring版本不兼容，于是试了多个版本之后依然无法访问，后看到配置类中有的地方可以改动，于是是这改动配置类，还有把静态资源页面放在resouces新建的META-INF目录下的resouces里，文件在你使用相应的版本的叫jar包里找（把jar包解压或者去他的网站里下对应版本的）。

我的Spring版本是2.1.6

1.使用的swagger2的pom：

   io.springfox
   springfox-swagger2
   2.9.2



   io.swagger.core.v3
   swagger-annotations
   2.1.0


   io.swagger.core.v3
   swagger-models
   2.1.0


   io.springfox
   springfox-swagger-ui
   2.9.2


   com.github.xiaoymin
   swagger-bootstrap-ui
   1.9.5

2.我的Swagger2配置类：

/** 在线接口文档
 * @projectname yunju
 * @author GEEKCJJ
 * @date 2019年8月5日 上午10:53:56
 * @description:
 *
 */
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUi
//@Import(BeanValidatorPluginsConfiguration.class)
/**
     * 将Swagger2 的swagger-ui.html加入资源路径下,否则Swagger2静态页面不能访问。要想使资源能够访问，可以有两种方法
     * 一：需要配置类继承WebMvcConfigurationSupport 类，实现addResourceHandlers方法。
     *      但是实现了WebMvcConfigurationSupport以后，Spring Boot的 WebMvc自动配置就会失效，具体表现比如访问不到
     *      静态资源（js，css等）了，这是因为WebMvc的自动配置都在WebMvcAutoConfiguration类中，但是类中有这个注解
     *      @ConditionalOnMissingBean({WebMvcConfigurationSupport.class})，意思是一旦在容器中检测到
     *      WebMvcConfigurationSupport这个类，WebMvcAutoConfiguration类中的配置都不生效。
     *      所以一旦我们自己写的配置类继承了WebMvcConfigurationSupport，相当于容器中已经有了WebMvcConfigurationSupport，
     *      所有默认配置都不会生效，都得自己在配置文件中配置。
     * 二：继承WebMvcConfigurer接口，这里采用此方法 网上有人说使用该方法会导致date编译等问题，可能在配置文件中得到解决，
     *      本人没有碰到，不多做解释
     * @param registry
     */
//我使用继承WebMvcConfigurationSupport类
public class SwaggerConfig extends WebMvcConfigurationSupport{//implements WebMvcConfigurer
	@Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.mk.mkqy.controller"))
                .paths(PathSelectors.any())
                .build();
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XXXX API 接口文档")
                .description("XXXX")
                .termsOfServiceUrl("http://XXXX.XXX/")
                .contact(new Contact("Maike","http://XXXX.XXX/","[email protected]"))
                .version("1.0")
                .build();
    }
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
        .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
        .addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("doc.html")
        .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
        .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

我把jar包里META-INF中resources中的html放在resources下新建的META-INF中的resources：

3.在controller中

@RestController
@Api(tags="查看文章",value="查看我的文章")
public class ArticleController extends BaseController{

    @Resource
    private ArticleMapper articleMapper;

    @ApiOperation(value="我的个人中心", notes="查看我发布的文章")
    @RequestMapping("querySelfArticle")
    public ResponseVo> querySelfArticle(HttpSession session){
        CustomerLogin login =getCurrentUser(session);
        String customId=login.getCustomerId();
        Wrapper
 wrapper=new QueryWrapper<>();
        ((QueryWrapper
) wrapper).eq("customer_id",customId);
        //返回一个list集合
        List
 articles=articleMapper.selectList(wrapper);
        return ResponseVo.response(200,"请求成功",articles);
    }
}

 

4.另外我用了美化文档的swagger-bootstrap-ui这个pom文件，里面的doc.html就是从swagger-bootstrap-ui提取的，这样就好看也好整理成pdf和doc文档。swagger-bootstrap-ui里面提供markdown形式的API文档。

swagger-ui的界面：

bootstrapui美化的文档界面：