当前位置：首页 > news >正文

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

news 2025/9/10 19:13:48

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的依赖

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

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>${swagger.fox.version}</version>
</dependency>

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

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>3.0.2</version>
</dependency>

<dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version>
</dependency>

三、代码配置

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

@Data
@Component
@ConfigurationProperties("swagger")
public class SwaggerProperties
{/*** 是否开启swagger*/private Boolean enabled;/*** swagger会解析的包路径**/private String basePackage = "";/*** swagger会解析的url规则**/private List<String> basePath = new ArrayList<>();/*** 在basePath基础上需要排除的url规则**/private List<String> 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<String> DEFAULT_EXCLUDE_PATH = Arrays.asList("/error", "/actuator/**");private static final String BASE_PATH = "/**";@Bean@ConditionalOnMissingBeanpublic SwaggerProperties swaggerProperties(){return new SwaggerProperties();}@Beanpublic Docket api(SwaggerProperties swaggerProperties){// base-path处理if (swaggerProperties.getBasePath().isEmpty()){swaggerProperties.getBasePath().add(BASE_PATH);}// noinspection uncheckedList<Predicate<String>> basePath = new ArrayList<Predicate<String>>();swaggerProperties.getBasePath().forEach(path -> basePath.add(PathSelectors.ant(path)));// exclude-path处理if (swaggerProperties.getExcludePath().isEmpty()){swaggerProperties.getExcludePath().addAll(DEFAULT_EXCLUDE_PATH);}List<Predicate<String>> 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
{@Overridepublic 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
{}