自定义文档

WARNING

自定义文档是knife4j提供的增强功能,开发者要想使用knife4j提供的增强功能,必须在Swagger的配置文件中引入增强注解,各个版本的增强注解区别如下表:

软件 版本 增强注解 说明
knife4j <=2.0.0 @EnableSwaggerBootstrapUi
knife4j >=2.0.1 @EnableKnife4j 后续版本不会再更改
  • 在使用knife4j的<=2.0.0版本之前的代码方式,代码示例如下:
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUi
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {
    
 //more..

}
  • 在使用knife4j的>=2.0.1版本之后的代码方式,代码示例如下:
@Configuration
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {
    
 //more..

}

后端开启增强注解后,还需要再前端个性化配置中勾选启用增强,整个配置才生效,如下图:

效果说明

knife4j为了满足文档的个性化配置,添加了自定义文档功能

开发者可自定义md文件扩展补充整个系统的文档说明

开发者可以在当前项目中添加一个文件夹,文件夹中存放.md格式的markdown文件,每个.md文档代表一份自定义文档说明

注意:自定义文档说明必须以.md结尾的文件,其他格式文件会被忽略

例如项目结构如下:

每个.md文件中,swagger-bootstrap-ui允许一级(h1)、二级(h2)、三级(h3)标题作为最终的文档标题

比如api.md文档:

# 自定义文档说明

## 效果说明

`knife4j`为了满足文档的个性化配置,添加了自定义文档功能

开发者可自定义`md`文件扩展补充整个系统的文档说明

开发者可以在当前项目中添加一个文件夹,文件夹中存放`.md`格式的markdown文件,每个`.md`文档代表一份自定义文档说明

**注意**:自定义文档说明必须以`.md`结尾的文件,其他格式文件会被忽略

最终在knife4j的界面中,api.md的文档标题会是自定义文档说明

整个文档效果如下:

如果没有按照一级(h1)、二级(h2)、三级(h3)来设置标题,默认标题会是文件名称,如图上的api2.md

如何使用

Spring Boot环境

在SpringBoot环境中,首先需要在application.yml或者application.properties配置文件中配置自定义文档目录

如下:

knife4j:
  markdowns: classpath:markdown/*

然后在Swagger的配置文件中启用@EnableKnife4j注解

如下代码:

@Configuration
@EnableSwagger2
@EnableKnife4j
public class SwaggerConfiguration {
    //more...
    
}

demo示例

以上两种不同环境的demo示例可参考swagger-bootstrap-ui-demo

被围观 人次
上次更新: 2020-3-8 14:15:27