springboot整合knife4j接口文档成公共模块使用

---

theme: smartblue

之前项目中一直用的是swagger-ui进行接口文档的调用和使用，最近前端一直反馈页面不美观，调用凌乱，等一系列问题。基于这个问题我决定将其进行更改调整，上网搜索了一下发现knife4j是目前接口文档不错的一款插件。打算将其替换swagger。

一、替换后的成果

1.替换前的:

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-8xQNn7kU-1681872792230)(https://p9-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/5e6b4ed10d834df8a40b266be1ad754c~tplv-k3u1fbpfcp-watermark.image?)]

2. 替换后的:

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-Ens6k7i4-1681872792231)(https://p1-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/b252607b7a8244c0a984f85c604d954b~tplv-k3u1fbpfcp-watermark.image?)]

是不是清晰多了

二、导入knife4j的依赖

1. 首先将原来swagger中的依赖注释或者去掉 如下：

    io.springfox
    springfox-swagger2
    ${swagger.fox.version}

2.引入knife4j依赖（这个knife4j如果我们使用的jdk是java8的话，基本版本是3的就够用）

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

    io.springfox
    springfox-boot-starter
    3.0.0

三、代码配置

3.1实体代码配置-接收knife4j路径配置和swagger一样

@Data
@Component
@ConfigurationProperties("swagger")
public class SwaggerProperties
{
    /**
     * 是否开启swagger
     */
    private Boolean enabled;

    /**
     * swagger会解析的包路径
     **/
    private String basePackage = "";

    /**
     * swagger会解析的url规则
     **/
    private List basePath = new ArrayList<>();

    /**
     * 在basePath基础上需要排除的url规则
     **/
    private List excludePath = new ArrayList<>();

    /**
     * 标题
     **/
    private String title = "";

    /**
     * 描述
     **/
    private String description = "";

    /**
     * 版本
     **/
    private String version = "";

    /**
     * 许可证
     **/
    private String license = "";

    /**
     * 许可证URL
     **/
    private String licenseUrl = "";

    /**
     * 服务条款URL
     **/
    private String termsOfServiceUrl = "";

    /**
     * host信息
     **/
    private String host = "";

    /**
     * 联系人信息
     */
    private Contact contact = new Contact();

    /**
     * 全局统一鉴权配置
     **/
    private Authorization authorization = new Authorization();
    }

3.2 使用到EnableSwagger2注解，开启knife4j

@Configuration
@EnableSwagger2
@EnableAutoConfiguration
@ConditionalOnProperty(name = "swagger.enabled", matchIfMissing = true)
public class SwaggerAutoConfiguration
{
    /**
     * 默认的排除路径，排除Spring Boot默认的错误处理路径和端点
     */
    private static final List DEFAULT_EXCLUDE_PATH = Arrays.asList("/error", "/actuator/**");

    private static final String BASE_PATH = "/**";

    @Bean
    @ConditionalOnMissingBean
    public SwaggerProperties swaggerProperties()
    {
        return new SwaggerProperties();
    }

    @Bean
    public Docket api(SwaggerProperties swaggerProperties)
    {
        // base-path处理
        if (swaggerProperties.getBasePath().isEmpty())
        {
            swaggerProperties.getBasePath().add(BASE_PATH);
        }
        // noinspection unchecked
        List> basePath = new ArrayList>();
        swaggerProperties.getBasePath().forEach(path -> basePath.add(PathSelectors.ant(path)));

        // exclude-path处理
        if (swaggerProperties.getExcludePath().isEmpty())
        {
            swaggerProperties.getExcludePath().addAll(DEFAULT_EXCLUDE_PATH);
        }

        List> excludePath = new ArrayList<>();
        swaggerProperties.getExcludePath().forEach(path -> excludePath.add(PathSelectors.ant(path)));

        ApiSelectorBuilder builder = new Docket(DocumentationType.SWAGGER_2).host(swaggerProperties.getHost())
                .apiInfo(apiInfo(swaggerProperties)).select()
                .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage()));

        swaggerProperties.getBasePath().forEach(p -> builder.paths(PathSelectors.ant(p)));
        swaggerProperties.getExcludePath().forEach(p -> builder.paths(PathSelectors.ant(p).negate()));

        return builder.build();
    }

 

    private ApiInfo apiInfo(SwaggerProperties swaggerProperties)
    {
         return new ApiInfoBuilder()
             .title(swaggerProperties.getTitle())
             .description(swaggerProperties.getDescription())
             .license(swaggerProperties.getLicense())
             .licenseUrl(swaggerProperties.getLicenseUrl())
             .termsOfServiceUrl(swaggerProperties.getTermsOfServiceUrl())
             .contact(new Contact(swaggerProperties.getContact().getName(), swaggerProperties.getContact().getUrl(), swaggerProperties.getContact().getEmail()))
             .version(swaggerProperties.getVersion())
             .build();
    }
}

3.3 路径地址的配置

这样页面访问就可以：http:ip:端口/doc.html进行访问了

@Configuration
public class SwaggerWebConfiguration 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("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

3.5 重点：切记spring.factories中进行配置SwaggerAutoConfiguration和SwaggerWebConfiguration

大家可以自定义一个注解，这样其他模块就可以直接用swagger了，不需要每个模块都配置，下面是我的一个配置

@Target({ ElementType.TYPE })
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
@Import({ SwaggerAutoConfiguration.class })
public @interface EnableCustomSwagger2
{

}

其他模块直接将swagger这个公共依赖引入，可以直接开启swagger使用了，界面如文章开头替换后swagger后的界面，大家可以参考！