SpringDoc + Knife4j的配置参考示例

原创已于 2025-11-06 23:42:51 修改 · 872 阅读

16 ·

CC 4.0 BY-SA版权

文章标签：

#java #spring boot #spring cloud

于 2025-09-27 11:53:32 首次发布

Spring Boot 从入门到精通：掌握现代化后端开发专栏收录该内容

64 篇文章

订阅专栏

【投稿赢 iPhone 17】「我的第一个开源项目」故事征集：用代码换C位出道！ 10w+人浏览 1.6k人参与

以下是 Spring Boot 3 项目中 application.yml 文件中 springdoc-openapi 和 knife4j 的完整、详细配置示例，每个配置项都带有中文注释说明其作用和推荐值，适用于企业级生产项目。

✅ SpringDoc OpenAPI + Knife4j 完整配置详解（application.yml）

# ==================== SpringDoc OpenAPI 核心配置 ====================
springdoc:
  # 是否启用 OpenAPI 3 接口（生产环境建议关闭）
  api-docs:
    enabled: true                    # 是否启用 /v3/api-docs 接口，默认 true
    path: /v3/api-docs               # OpenAPI JSON 接口路径，默认 /v3/api-docs
    groups:
      enabled: false                 # 是否启用分组（多版本 API 时使用）

  # Swagger UI 原生界面配置（Knife4j 会覆盖大部分，但保留兼容）
  swagger-ui:
    enabled: true                    # 是否启用原生 Swagger UI，默认 true
    path: /swagger-ui.html           # 原生 UI 访问路径（Knife4j 使用 /doc.html）
    disable-swagger-default-url: true # 禁用默认 Petstore 示例 URL
    supported-submit-methods:        # 支持的提交方法（调试用）
      - get
      - post
      - put
      - delete
    tags-sorter: alpha               # 标签排序：alpha=字母序，method=方法序
    operations-sorter: method        # 操作排序：alpha=字母序，method=请求方法序
    try-it-out-enabled: true         # 是否启用 "Try it out" 调试按钮
    filter: false                    # 是否显示过滤框（按标签过滤）
    syntax-highlight:                # 语法高亮
      activated: true
      theme: atom-one-dark           # 高亮主题：agate, arta, atom-one-dark 等

  # 默认媒体类型（影响 Content-Type 和 Accept）
  default-produces-media-type: application/json
  default-consumes-media-type: application/json

  # 包扫描配置（默认扫描所有 @RestController）
  packages-to-scan:                # 指定扫描的包（可选，用于多模块项目）
    - com.example.demo.controller
  packages-to-exclude:             # 排除的包（如内部接口）
    - com.example.demo.internal

  # 路径配置（可忽略某些路径）
  paths-to-match:                  # 只匹配这些路径（默认全部）
    - /api/**
  paths-to-exclude:                # 排除这些路径（如健康检查）
    - /actuator/**
    - /internal/**

  # 全局操作参数（所有接口自动添加的参数，如 token、traceId）
  global-parameters:
    - name: Authorization
      description: "Bearer Token 认证"
      in: header
      required: false
      schema:
        type: string
      example: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# ==================== Knife4j 增强配置（企业级功能） ====================
knife4j:
  # 是否启用 Knife4j（生产环境设为 false）
  enable: true

  # 生产环境模式（开启后屏蔽调试、导出等功能，即使 enable=true）
  production: false

  # 基础认证（访问文档需登录）
  basic-auth:
    enable: false                  # 是否开启基础认证
    username: admin                # 认证用户名
    password: 123456               # 认证密码

  # 界面设置（UI 个性化）
  setting:
    # 语言设置
    language: zh-CN                # 界面语言：zh-CN（中文），en-US（英文）

    # 缓存设置
    cache: true                    # 是否缓存参数（刷新页面不丢失调试参数）

    # 页脚设置
    enableFooter: false            # 是否显示页脚
    enableFooterCustom: false      # 是否启用自定义页脚
    footerCustomContent: "© 2025 企业 API 文档系统" # 自定义页脚内容

    # 搜索功能
    enableSearch: true             # 是否启用搜索框（按接口名/描述搜索）

    # OpenAPI 规范按钮
    enableOpenApi: true            # 是否显示 "OpenAPI" 按钮（查看原始 JSON）

    # Schemas 模型显示
    enableSwaggerModels: true      # 是否显示 "Schemas" 标签页（DTO/VO 结构）

    # 调试功能
    enableAfterScript: true        # 是否启用 AfterScript（调试后执行脚本）
    enableDocumentManage: true     # 是否启用文档管理（离线文档、导出等）
    enableDynamicParameter: true   # 是否启用动态参数（调试时动态添加参数）

    # 主题与样式
    theme: default                 # 主题：default, dark, material, layui 等
    showCode: true                 # 是否显示状态码说明

    # 分组设置（多版本 API 时使用）
    enableGroup: false             # 是否启用分组（需配合 springdoc.groups）

  # 文档导出设置（企业常用）
  documents:
    create:
      # 导出 HTML（单页）
      - group: "用户服务"
        name: "用户管理API文档"
        locations: classpath:markdown/user.md # 自定义 Markdown 描述文件
        swaggerUiLink: true        # 是否显示跳转到 Swagger UI 的链接
      # 导出 Word（需额外依赖）
      - group: "订单服务"
        name: "订单API文档"
        type: word                 # 导出类型：html, markdown, word, openapi

  # CORS 配置（如前端独立部署）
  cors:
    enable: false
    allow-credentials: true
    allowed-headers: "*"
    allowed-methods: "*"
    allowed-origins: "*"

  # 网关聚合配置（Spring Cloud Gateway 项目使用）
  gateway:
    discover:
      enabled: false               # 是否启用服务发现（自动聚合微服务）
    strategies:
      - service-name: user-service # 下游服务名
        context-path: /user        # 网关路由前缀
      - service-name: order-service
        context-path: /order

  # 安全拦截（自定义权限控制）
  secure:
    enable: false                  # 是否启用安全拦截
    roles:                         # 允许访问的角色（需集成 Spring Security）
      - ROLE_ADMIN
      - ROLE_DEV

# ==================== 可选：日志与监控 ====================
logging:
  level:
    io.swagger: WARN              # 降低 Swagger 日志级别
    org.springdoc: WARN

management:
  endpoints:
    web:
      exposure:
        include: health,info      # 暴露健康检查端点（排除在 API 文档外）

✅ 配置项分类说明

一、`springdoc` 配置作用

配置项	作用	推荐值
`api-docs.enabled`	是否生成 OpenAPI JSON 接口	开发环境 `true`，生产环境 `false`
`api-docs.path`	OpenAPI JSON 路径	`/v3/api-docs`（默认）
`swagger-ui.path`	原生 Swagger UI 路径	`/swagger-ui.html`（Knife4j 用 `/doc.html`）
`packages-to-scan`	指定扫描 Controller 包	多模块项目推荐指定
`paths-to-exclude`	排除某些路径（如 Actuator）	必须排除 `/actuator/**`
`global-parameters`	全局参数（如 Token）	推荐添加 `Authorization`

二、`knife4j` 配置作用

配置项	作用	推荐值
`enable`	是否启用 Knife4j UI	开发环境 `true`，生产环境 `false`
`production`	生产模式（屏蔽敏感功能）	生产环境 `true`
`basic-auth.enable`	是否开启登录认证	企业内网可开启
`setting.language`	界面语言	`zh-CN`（中文）
`setting.cache`	是否缓存调试参数	`true`（提升体验）
`setting.theme`	界面主题	`default` 或 `dark`
`setting.enableDocumentManage`	是否启用文档导出	`true`（企业推荐）
`documents.create`	自定义导出文档	按需配置 HTML/Word
`gateway.discover.enabled`	是否聚合微服务	网关项目设为 `true`

✅ 生产环境推荐配置（application-prod.yml）

springdoc:
  api-docs:
    enabled: false   # 关闭 OpenAPI 接口
  swagger-ui:
    enabled: false   # 关闭原生 UI

knife4j:
  enable: false      # 关闭 Knife4j
  production: true   # 开启生产模式（双重保险）

或通过启动参数禁用：

java -jar app.jar --springdoc.api-docs.enabled=false --knife4j.enable=false

✅ 开发环境推荐配置（application-dev.yml）

springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    enabled: true

knife4j:
  enable: true
  production: false
  basic-auth:
    enable: false    # 开发环境可关闭认证
  setting:
    language: zh-CN
    cache: true
    enableDocumentManage: true

✅ 多环境激活配置（application.yml）

spring:
  profiles:
    active: dev      # 默认激活开发环境

---
spring:
  config:
    activate:
      on-profile: dev
# 引用 application-dev.yml 内容

---
spring:
  config:
    activate:
      on-profile: prod
# 引用 application-prod.yml 内容

✅ 配置验证

启动项目后访问：

🔹 Knife4j UI：http://localhost:8080/doc.html
🔹 原生 Swagger UI：http://localhost:8080/swagger-ui.html
🔹 OpenAPI JSON：http://localhost:8080/v3/api-docs

检查：

✅ 界面是否为 Knife4j 增强风格
✅ 是否按配置排除了 Actuator 路径
✅ 是否支持中文、缓存、导出等功能
✅ 生产环境是否正确关闭

✅ 总结：企业级配置最佳实践

场景	配置策略
开发环境	开启所有功能，中文界面，参数缓存，文档导出
测试环境	开启 Knife4j，关闭原生 UI，可开启 Basic Auth
生产环境	完全关闭 API 文档（`enable=false`），或仅限内网 IP 访问
微服务网关	开启 `gateway.discover.enabled=true`，聚合下游服务
安全要求高	开启 `basic-auth` 或集成 Spring Security 权限控制