Knife4j Next

Appearance

配置参考 ​

本页列出所有 knife4j.* YAML 配置属性，按使用场景分组。

属性源自 @ConfigurationProperties 类定义。部分 UI 配置在 React 前端暂不生效，已用 ⚠️ 标注。

WebMvc Starter 通用配置 ​

适用于 knife4j-openapi2-spring-boot-starter、knife4j-openapi3-spring-boot-starter、knife4j-openapi3-jakarta-spring-boot-starter。

knife4j.* ​

属性类型默认值说明
knife4j.enablebooleanfalse启用 knife4j 增强模式（openapi2 必须设为 true；openapi3 可选）
knife4j.corsbooleanfalse启用默认跨域支持
knife4j.productionbooleanfalse生产环境：设为 true 后 /doc.html、/v2/api-docs、/v3/api-docs 等返回 403
knife4j.openapiObject—OpenAPI 基本信息（仅 openapi2 starter，见下文）
knife4j.basicObject—HTTP Basic 认证配置，见下文
knife4j.settingObject—UI 个性化配置，见下文
knife4j.documentsList—自定义 Markdown 文档分组，见下文
knife4j.insightObject—Knife4jInsight 配置，见下文

knife4j.basic.* ​

属性类型默认值说明
knife4j.basic.enablebooleanfalse启用 Basic 认证
knife4j.basic.usernameString—用户名
knife4j.basic.passwordString—密码
knife4j.basic.includeList<String>—需要认证的 URL（正则表达式，since 4.1.0）

knife4j.setting.* ​

属性类型默认值说明React UI
knife4j.setting.languageZH_CN / ENZH_CN界面语言⚠️ 暂不生效
knife4j.setting.enableSwaggerModelsbooleantrue显示 Swagger Models 功能⚠️
knife4j.setting.swaggerModelNameString"Swagger Models"Swagger Models 名称⚠️
knife4j.setting.enableDocumentManagebooleantrue显示文档管理功能⚠️
knife4j.setting.enableReloadCacheParameterbooleanfalse显示调试后刷新变量按钮⚠️
knife4j.setting.enableAfterScriptbooleantrue显示 afterScript 功能⚠️
knife4j.setting.enableVersionbooleanfalse启用接口版本控制⚠️
knife4j.setting.enableRequestCachebooleantrue启用请求参数缓存⚠️
knife4j.setting.enableFilterMultipartApisbooleanfalse过滤 RequestMapping 多方法显示⚠️
knife4j.setting.enableFilterMultipartApiMethodTypeString"POST"过滤方法类型⚠️
knife4j.setting.enableHostbooleanfalse启用 Host⚠️
knife4j.setting.enableHostTextString""Host 地址⚠️
knife4j.setting.enableDynamicParameterbooleanfalse启用动态请求参数⚠️
knife4j.setting.enableDebugbooleantrue启用调试功能⚠️
knife4j.setting.enableFooterbooleantrue显示底部 Footer⚠️
knife4j.setting.enableFooterCustombooleanfalse自定义 Footer⚠️
knife4j.setting.footerCustomContentString—自定义 Footer 内容（支持 Markdown）⚠️
knife4j.setting.enableSearchbooleantrue显示搜索框⚠️
knife4j.setting.enableOpenApibooleantrue显示 OpenAPI 原始结构 Tab⚠️
knife4j.setting.enableHomeCustombooleanfalse启用首页自定义⚠️
knife4j.setting.homeCustomLocationString—首页自定义 Markdown 文件路径⚠️
knife4j.setting.enableGroupbooleantrue显示分组下拉框⚠️
knife4j.setting.enableResponseCodebooleantrue显示响应状态码栏⚠️
knife4j.setting.customCodeInteger200生产环境屏蔽时的自定义 HTTP 状态码✅

标 ⚠️ 的配置在 React 新前端中暂不生效（后端会写入 OpenAPI extension，但前端不读取）。详见 FAQ。

knife4j.documents（列表） ​

yaml
knife4j:
  documents:
    - group: 2.X版本
      name: 测试文档
      locations: classpath:markdown/*
属性类型说明
groupString所属分组
nameString文档名称
locationsStringMarkdown 文件路径（classpath 前缀）

knife4j.insight.*（since 4.4.0） ​

属性类型默认值说明
knife4j.insight.enablebooleanfalse启用 Knife4jInsight 自动上传
knife4j.insight.serverString—Insight 数据源地址（如 http://console.knife4j.net）
knife4j.insight.secretString—上传凭证密钥
knife4j.insight.namespaceString—上传命名空间（默认从应用名生成）
knife4j.insight.serviceNameString—上传服务名（默认取 spring.application.name）

knife4j.openapi.*（仅 openapi2 starter） ​

属性类型默认值说明
knife4j.openapi.titleString—文档标题
knife4j.openapi.descriptionString—描述
knife4j.openapi.versionString—版本号
knife4j.openapi.emailString—联系邮箱
knife4j.openapi.urlString—主页 URL
knife4j.openapi.concatString—联系人
knife4j.openapi.termsOfServiceUrlString—服务条款 URL
knife4j.openapi.licenseString—许可证
knife4j.openapi.licenseUrlString—许可证 URL
knife4j.openapi.groupMap—分组配置（key 为分组名）

knife4j.openapi.group.<name>.*

属性类型说明
groupNameString分组名称
apiRulePACKAGE / ANNOTATIONAPI 扫描策略
apiRuleResourcesList<String>策略对应资源（包名或注解类名）
pathRuleANT / REGEX路径匹配策略
pathRuleResourcesList<String>路径资源

Gateway Starter 配置 ​

适用于 knife4j-gateway-spring-boot-starter。

knife4j.gateway.* ​

属性类型默认值说明
knife4j.gateway.enabledbooleanfalse启用 Gateway 聚合
knife4j.gateway.strategyMANUAL / DISCOVERMANUAL聚合策略
knife4j.gateway.tagsSorteralpha / orderalphaTag 排序规则
knife4j.gateway.operationsSorteralpha / orderalphaOperation 排序规则
knife4j.gateway.basicObject—Basic 认证（同 knife4j.basic）
knife4j.gateway.discoverObject—服务发现配置
knife4j.gateway.routesList—手动路由配置

knife4j.gateway.discover.* ​

属性类型默认值说明
enabledBooleanFALSE启用服务发现
excludedServicesSet<String>—排除的服务名（支持正则，since 4.3.0）
versionOpenAPI3 / Swagger2OpenAPI3规范版本

knife4j.gateway.routes[] ​

yaml
knife4j:
  gateway:
    enabled: true
    routes:
      - name: 用户服务
        serviceName: user-service
        url: /v3/api-docs
        contextPath: /
        order: 1
属性类型默认值说明
nameString—分组名称（UI 显示）
serviceNameString—服务名
urlString"/v2/api-docs?group=default"OpenAPI 数据源路径
contextPathString"/"上下文路径（since 4.1.0）
orderInteger0排序（升序）

聚合 Starter 配置 ​

适用于 knife4j-aggregation-spring-boot-starter 和 knife4j-aggregation-jakarta-spring-boot-starter。

knife4j.enableAggregation ​

属性类型默认值说明
knife4j.enableAggregationbooleanfalse启用聚合模式

knife4j.disk.* ​

属性类型默认值说明
knife4j.disk.enablebooleanfalse启用 Disk 模式
knife4j.disk.routesList—Disk 路由列表

knife4j.disk.routes[]

属性类型默认值说明
nameString—服务名（UI 分组显示）
locationString—OpenAPI 文件路径（classpath 或 URL）
debugUrlString—调试目标 URL
swaggerVersionString"2.0"规范版本（2.0 或 3.0）
servicePathString—微服务路径（网关 basePath）
orderInteger1排序

knife4j.cloud.* ​

属性类型默认值说明
knife4j.cloud.enablebooleanfalse启用 Cloud 模式
knife4j.cloud.routesList—Cloud 路由列表
knife4j.cloud.routeAuthObject—通用路由认证

knife4j.cloud.routes[]

属性类型说明
nameString服务名
uriStringOpenAPI 实例 URI（如 http://192.168.0.1:8999）
locationStringOpenAPI 文件路径
debugUrlString调试目标 URL
swaggerVersionString规范版本
servicePathString微服务路径
routeAuthObject路由级认证（覆盖通用配置）
orderInteger排序

knife4j.nacos.* ​

属性类型默认值说明
knife4j.nacos.enablebooleanfalse启用 Nacos 模式
knife4j.nacos.serviceUrlString—Nacos 地址（如 http://192.168.0.1:8848/nacos）
knife4j.nacos.secretString—接口访问密钥
knife4j.nacos.serviceAuthObject—Nacos 注册中心认证
knife4j.nacos.routeAuthObject—通用路由认证
knife4j.nacos.routesList—Nacos 路由列表

knife4j.nacos.routes[]

属性类型说明
serviceNameString服务名（必填）
groupNameStringNacos 分组
namespaceIdString命名空间 ID
clustersString集群名（逗号分隔）
(继承 CommonRoute) name, location, debugUrl, swaggerVersion, servicePath, order, routeAuth同 Cloud 路由

knife4j.eureka.* ​

属性类型默认值说明
knife4j.eureka.enablebooleanfalse启用 Eureka 模式
knife4j.eureka.serviceUrlString—Eureka 地址（如 http://localhost:10000/eureka/）
knife4j.eureka.serviceAuthObject—Eureka 注册中心认证
knife4j.eureka.routeAuthObject—通用路由认证
knife4j.eureka.routesList—Eureka 路由列表

knife4j.eureka.routes[]

属性类型说明
serviceNameString服务名（必填）
(继承 CommonRoute) name, location, debugUrl, swaggerVersion, servicePath, order, routeAuth同 Cloud 路由

knife4j.polaris.* ​

属性类型默认值说明
knife4j.polaris.enablebooleanfalse启用 Polaris 模式
knife4j.polaris.serviceUrlString—Polaris 地址
knife4j.polaris.serviceAuthObject—Polaris 注册中心认证
knife4j.polaris.jwtCookieString—接口访问 JWT Cookie
knife4j.polaris.routeAuthObject—通用路由认证
knife4j.polaris.routesList—Polaris 路由列表

knife4j.polaris.routes[]

属性类型说明
serviceString服务名（必填）
namespaceString命名空间 ID
(继承 CommonRoute) name, location, debugUrl, swaggerVersion, servicePath, order, routeAuth同 Cloud 路由

knife4j.openapiv3.*（聚合 Jakarta 版） ​

属性类型默认值说明
knife4j.openapiv3.urlString"/v3/api-docs"OpenAPI 数据源 URL
knife4j.openapiv3.oauth2RedirectUrlString""OAuth2 重定向 URL
knife4j.openapiv3.validatorUrlString""Validator URL
knife4j.openapiv3.tagsSorteralpha / orderalphaTag 排序规则（since 4.5.0）
knife4j.openapiv3.operationsSorteralpha / orderalphaOperation 排序规则（since 4.5.0）

knife4j.basic-auth.*（聚合版） ​

属性类型默认值说明
knife4j.basic-auth.enablebooleanfalse启用认证
knife4j.basic-auth.usernameString—用户名
knife4j.basic-auth.passwordString—密码

knife4j.connection-setting.* ​

属性类型默认值说明
knife4j.connection-setting.socketTimeoutint10000Socket 超时（ms）
knife4j.connection-setting.connectTimeoutint10000连接超时（ms）
knife4j.connection-setting.maxConnectionTotalint200最大连接数
knife4j.connection-setting.maxPreRouteint20单路由最大连接数

配置示例 ​

最小配置（WebMvc + OpenAPI3） ​

yaml
knife4j:
  enable: true

springdoc:
  swagger-ui:
    path: /swagger-ui.html
  api-docs:
    path: /v3/api-docs

生产环境配置 ​

yaml
knife4j:
  enable: true
  production: true
  basic:
    enable: true
    username: admin
    password: ${DOC_PASSWORD}

Gateway 聚合配置（DISCOVER 模式） ​

yaml
knife4j:
  gateway:
    enabled: true
    strategy: discover
    discover:
      enabled: true
      version: openapi3
      excludedServices:
        - gateway-service
    basic:
      enable: true
      username: admin
      password: ${DOC_PASSWORD}

Nacos 聚合配置 ​

yaml
knife4j:
  enableAggregation: true
  nacos:
    enable: true
    serviceUrl: http://127.0.0.1:8848/nacos
    routes:
      - name: 用户服务
        serviceName: user-service
        groupName: DEFAULT_GROUP
        namespaceId: public

让 OpenAPI 文档更清晰，让接口联调更顺手。

Apache-2.0 · Knife4j Next