Swagger/Knife4j 配置解析指南

配置项识别逻辑

在提供 Swagger/Knife4j 访问指引前，AI 应按以下顺序检查项目配置文件：

1. 定位配置文件

检查以下文件（按优先级）：

1. <project-name>-start/src/main/resources/application.yml
2. <project-name>-start/src/main/resources/application.properties
3. <project-name>-start/src/main/resources/application-{profile}.yml（如果有激活的 profile）

2. 提取关键配置项

A. 服务器端口（server.port）

YAML 格式示例：

server:
  port: 8080

Properties 格式示例：

server.port=8080

处理逻辑：

• ✅ 找到配置 → 使用配置的端口号
• ❌ 未找到配置 → 使用默认值 8080，并提示用户

B. 上下文路径（server.servlet.context-path）

YAML 格式示例：

server:
  servlet:
    context-path: /api

Properties 格式示例：

server.servlet.context-path=/api

处理逻辑：

• ✅ 找到配置 → 在 URL 中加入上下文路径
• ❌ 未找到配置 → 不使用上下文路径（根路径 /）

3. 构建访问 URL

URL 构建公式：

http://localhost:{port}/{context-path}/{swagger-path}

参数说明：

• {port}：从 server.port 提取，默认 8080
• {context-path}：从 server.servlet.context-path 提取，默认为空
• {swagger-path}：Swagger 文档路径（见下方）

Swagger 文档路径：

文档类型	路径
Knife4j	doc.html
Swagger UI	swagger-ui.html
Swagger JSON	v2/api-docs

---

常见配置场景示例

场景 1：默认配置（无自定义）

配置文件： 无 server.port 和 context-path 配置

生成的 URL：

• Knife4j：http://localhost:8080/doc.html
• Swagger UI：http://localhost:8080/swagger-ui.html

输出提示：

💡 使用默认端口 8080（未在配置文件中找到 server.port）

---

场景 2：自定义端口

配置文件（application.yml）：

server:
  port: 9090

生成的 URL：

• Knife4j：http://localhost:9090/doc.html
• Swagger UI：http://localhost:9090/swagger-ui.html

输出提示：

💡 检测到自定义端口：9090

---

场景 3：自定义端口 + 上下文路径

配置文件（application.yml）：

server:
  port: 8888
  servlet:
    context-path: /myapp

生成的 URL：

• Knife4j：http://localhost:8888/myapp/doc.html
• Swagger UI：http://localhost:8888/myapp/swagger-ui.html

输出提示：

💡 检测到自定义配置：端口 8888，上下文路径 /myapp

---

场景 4：仅自定义上下文路径

配置文件（application.properties）：

server.servlet.context-path=/api/v1

生成的 URL：

• Knife4j：http://localhost:8080/api/v1/doc.html
• Swagger UI：http://localhost:8080/api/v1/swagger-ui.html

输出提示：

💡 检测到上下文路径：/api/v1（使用默认端口 8080）

---

配置解析步骤（AI 执行流程）

当编译成功后，AI 应执行以下步骤：

步骤 1：读取配置文件

# 尝试读取 application.yml
cat <project-name>-start/src/main/resources/application.yml

# 或读取 application.properties
cat <project-name>-start/src/main/resources/application.properties

步骤 2：解析配置项

查找 server.port：

• 在 YAML 中搜索 port: 字段（在 server: 下）
• 在 Properties 中搜索 server.port= 行
• 提取数值，去除空格和注释

查找 server.servlet.context-path：

• 在 YAML 中搜索 context-path: 字段（在 server.servlet: 下）
• 在 Properties 中搜索 server.servlet.context-path= 行
• 提取路径字符串，去除引号和空格

步骤 3：应用默认值

# 伪代码逻辑
port = config.get('server.port') or 8080
context_path = config.get('server.servlet.context-path') or ''

# 确保 context-path 格式正确
if context_path and not context_path.startswith('/'):
    context_path = '/' + context_path

步骤 4：生成最终 URL

base_url = f"http://localhost:{port}{context_path}"

knife4j_url = f"{base_url}/doc.html"
swagger_ui_url = f"{base_url}/swagger-ui.html"

步骤 5：输出指引

根据解析结果生成相应的提示信息。

---

特殊情况处理

1. 多个 Profile 配置

如果项目有多个 application-{profile}.yml 文件：

• 检查 application.yml 中的 spring.profiles.active 配置
• 优先读取激活的 profile 配置文件
• 如果未指定 active profile，使用默认的 application.yml

2. 环境变量覆盖

提醒用户：

⚠️ 注意：如果通过环境变量或启动参数设置了端口，
   实际端口可能与配置文件不同。
   例如：java -jar app.jar --server.port=9090

3. HTTPS 配置

如果检测到 SSL 配置：

server:
  ssl:
    enabled: true

则使用 https:// 协议：

• Knife4j：https://localhost:8443/doc.html

4. Swagger 未集成

如果项目中未找到 Swagger/Knife4j 相关依赖：

⚠️ 注意：未在 pom.xml 中发现 Swagger/Knife4j 依赖。
   如需接口文档功能，请添加相应依赖后重新编译。

---

快速参考表

配置项	YAML 路径	Properties 键	默认值
端口	server.port	server.port	8080
上下文路径	server.servlet.context-path	server.servlet.context-path	/ (空)
SSL 启用	server.ssl.enabled	server.ssl.enabled	false
Active Profile	spring.profiles.active	spring.profiles.active	无

---

输出模板示例

模板 1：默认配置

2️⃣ 访问 Swagger 文档（启动成功后）：
   • Knife4j：http://localhost:8080/doc.html
   • Swagger UI：http://localhost:8080/swagger-ui.html
   
   💡 使用默认端口 8080

模板 2：自定义端口

2️⃣ 访问 Swagger 文档（启动成功后）：
   • Knife4j：http://localhost:9090/doc.html
   • Swagger UI：http://localhost:9090/swagger-ui.html
   
   💡 检测到自定义端口：9090

模板 3：自定义端口 + 上下文路径

2️⃣ 访问 Swagger 文档（启动成功后）：
   • Knife4j：http://localhost:8888/myapp/doc.html
   • Swagger UI：http://localhost:8888/myapp/swagger-ui.html
   
   💡 检测到自定义配置：端口 8888，上下文路径 /myapp

模板 4：无法读取配置

2️⃣ 访问 Swagger 文档（启动成功后）：
   • Knife4j：http://localhost:8080/doc.html
   • Swagger UI：http://localhost:8080/swagger-ui.html
   
   ⚠️ 未能读取配置文件，使用默认端口 8080。
      请检查 <project-name>-start/src/main/resources/application.yml