# 3.23 自定义主页内容
WARNING
增强功能需要通过配置yml配置文件开启增强,自2.0.8开始
knife4j:
enable: true
Knife4j自2.0.8
版本开始,开发者可以提供一个Markdown文件来自定义显示Home主页的显示内容,通过配置yml来进行开启,配置文件如下
knife4j:
enable: true
setting:
enableHomeCustom: true
homeCustomLocation: classpath:markdown/home.md
属性说明:
enableHomeCustom
:该属性为Boolean值,默认false
,如果开发者要自定义主页内容,该选项设置为true
homeCustomLocation
:提供一个主页的Markdown文件位置
开发者配置好后,最核心的一步,也是最后最重要的一步,开发者需要在创建Docket
逻辑分组对象时,通过Knife4j
提供的工具对象OpenApiExtensionResolver
将扩展属性进行赋值
示例代码如下:
点击查看代码
@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfiguration {
private final OpenApiExtensionResolver openApiExtensionResolver;
@Autowired
public SwaggerConfiguration(OpenApiExtensionResolver openApiExtensionResolver) {
this.openApiExtensionResolver = openApiExtensionResolver;
}
@Bean(value = "defaultApi2")
public Docket defaultApi2() {
String groupName="2.X版本";
Docket docket=new Docket(DocumentationType.SWAGGER_2)
.host("https://www.baidu.com")
.apiInfo(apiInfo())
.groupName(groupName)
.select()
.apis(RequestHandlerSelectors.basePackage("com.swagger.bootstrap.ui.demo.new2"))
.paths(PathSelectors.any())
.build()
.extensions(openApiExtensionResolver.buildSettingExtensions());
return docket;
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//.title("swagger-bootstrap-ui-demo RESTful APIs")
.description("# swagger-bootstrap-ui-demo RESTful APIs")
.termsOfServiceUrl("http://www.xx.com/")
.contact("xx@qq.com")
.version("1.0")
.build();
}
}
通过上面示例代码,主要步骤如下:
1、通过@Autowired
注解引入Knife4j
向Spring容器注入的Bean对象OpenApiExtensionResolver
2、最终在Dcoket
对象构建后,通过调用Docket
对象的extensions
方法进行插件赋值
3、插件赋值需要调用OpenApiExtensionResolver
提供的buildSettingExtensions
方法,获取x-settings
的增强属性
最终界面效果如下:
TIP
为什么需要这么做?这样做的目的一方面是充分利用Spring Boot提供的配置方式,方便开发者自定义配置属性,另一方面,通过扩展OpenAPI的规范属性,也更加符合OpenAPI对于扩展属性的要求
OpenAPI规范明确规定,对于扩展属性,开发者应当在响应的某个节点中,增加x-
开头的属性方式,以扩展自定义的属性配置
自定义文档的扩展属性,开发者可以通过浏览器的Network功能查看OpenAPI的结构,最终Knife4j扩展增加x-openapi
属性,代表增加的扩展自定义属性,最终在Ui界面解析呈现,结构如下图:
有任何问题请使用
Knife4j
的标签在OSC社区