# 3.28 禁用OpenApi结构显示

WARNING

增强功能需要通过配置yml配置文件开启增强,自2.0.8开始

knife4j:
  enable: true

开发者如果想要禁用Ui界面中的OpenAPI功能,需要通过增强属性进行配置(需要注意的是如果开发者直接禁用调试,那么OpenAPI默认也是不显示的),在yml配置如下:

knife4j:
  enable: true
  setting:
    enableOpenApi: false

属性说明:

  • enableOpenApi:该属性是一个Boolean值,代表是否启用OpenAPI功能,默认值为true(代表开启OpenAPI显示),如果要禁用OpenAPI显示,该值设为false

开发者配置好后,最核心的一步,也是最后最重要的一步,开发者需要在创建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界面解析呈现,结构如下图:

被围观 人次
上次更新: 2020/11/21 20:03:44
有任何问题请使用Knife4j的标签在OSC社区