以下是 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 权限控制 |
📌 提示：
- 配置不是越多越好，根据团队和项目需求调整。
- 生产环境务必关闭或保护 API 文档，避免信息泄露。
- 使用
@Profile或外部配置中心（Nacos/Consul）管理多环境配置。
通过以上详细配置，你可以在 Spring Boot 3 项目中安全、灵活、高效地使用 SpringDoc + Knife4j，打造专业级 API 文档系统！
2万+
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
