接口文档
接口文档用于研发、测试和前端联调查看后端 OpenAPI/Knife4j 接口。RuoYi Office 管理端入口位于 apps/web-antd/src/views/infra/swagger/index.vue，默认 iframe 打开 ${VITE_BASE_URL}/doc.html；如果系统配置 url.swagger 有值，则优先使用该地址。
访问入口
| 场景 | 默认地址 | 说明 |
|---|---|---|
| 单体后端 | /doc.html | Knife4j UI，通常在后端 48080 下访问 |
| 管理端内嵌 | views/infra/swagger | 通过 IFrame 内嵌，自动读取 url.swagger 配置 |
| 启动日志 | BannerApplicationRunner | 后端启动成功后打印接口文档地址 |
工作链路
使用建议
- 优先通过管理端入口访问：可复用当前环境的后端地址，减少手工拼 URL 出错。
- 多环境配置
url.swagger：测试、预发、生产如果网关路径不同，建议通过系统配置覆盖。 - 接口调试注意鉴权：需要登录态、租户或 Token 的接口，直接在 Knife4j 调试前要确认请求头。
- 不要把生产接口文档暴露到公网：生产环境建议通过网关、白名单或权限策略限制访问。
排查清单
| 现象 | 优先检查 |
|---|---|
| 页面 404 | 后端是否启用接口文档；网关是否转发 /doc.html 与 OpenAPI 路径 |
| 管理端 iframe 空白 | VITE_BASE_URL、url.swagger、跨域与 CSP 配置 |
| 分组缺失 | 对应模块是否启动；Controller 是否有 OpenAPI 注解；包扫描是否包含模块 |
| 调试 401/403 | Token、租户、权限、请求头是否正确 |
