接口文档为什么会成为问题
Swagger UI 与 OpenAPI 描述文件在生产环境公开，等于把接口清单、参数结构、内部字段命名一并交出去：攻击者不必猜路径，可以按文档直接构造请求。这类暴露很少单独导致入侵，但它显著降低攻击成本，也常把内部管理接口一起暴露。处置不是一律删除，而是按环境区分：生产关闭，或改为内网访问加鉴权。
基本信息
| 常见路径 | /swagger-ui.html、/swagger-ui/index.html、/v2/api-docs、/v3/api-docs、/openapi.json、/docs |
|---|---|
| 直接后果 | 接口枚举、参数结构泄露、内部字段与示例数据泄露 |
| 间接风险 | 隐藏的管理接口与调试端点被一并发现 |
| 风险定级 | 中，取决于文档中是否含未授权或高危接口 |
| 处置方式 | 生产关闭、内网访问、加鉴权、清理示例中的真实数据 |
| 检查时机 | 上线前自查、季度暴露面巡检、接口变更后复核 |
常见路径与判断
| 路径 | 说明 | 期望结果 |
|---|---|---|
| /swagger-ui/index.html | UI 页面入口 | 公网返回 404 或跳转登录 |
| /v3/api-docs | OpenAPI 描述文件 | 需鉴权或仅内网可访问 |
| /v2/api-docs | 旧版 springfox 描述 | 老项目常遗留，需单独核查 |
| /openapi.json | 新框架默认描述文件 | 与 api-docs 同等对待 |
| /docs | 部分框架默认文档路径 | 返回 404 或鉴权拦截 |
| /actuator/mappings | 端点映射列表 | 生产应受限访问 |
常见路径自查
常见路径自查
# 逐一请求，确认是否需要鉴权、是否可从公网访问
for p in /swagger-ui/index.html /v3/api-docs /v2/api-docs /openapi.json /docs /actuator/mappings; do
code=$(curl -s -o /dev/null -w '%{http_code}' "https://example.com$p")
echo "$p -> $code" # 期望 401/403/404，返回 200 需人工确认内容
doneSpring 环境关闭示例
Spring 环境关闭示例
# application-prod.properties
springdoc.api-docs.enabled=false
springdoc.swagger-ui.enabled=false
# 旧版 springfox：springfox.documentation.enabled=false
# 若必须保留：加访问控制，仅内网网段或鉴权后才可访问
# 关闭后重启生效，并复核网关是否还有缓存或独立映射典型使用场景
- 新服务上线前的暴露面自查项
- 季度巡检中对文档路径的批量扫描
- 渗透测试报告里接口信息泄露类问题的整改
- 内部系统改为公网可访问时的复核
- 接口重构后确认旧文档路径已下线
- 安全左移：把文档检查写进上线清单
文档是开发提效工具，不必一刀切关闭。用内网域名加鉴权保留可用性，比让所有人都不方便更可持续，也更容易被团队接受并长期执行。
文档里常带真实测试数据、内部字段命名与内网地址，扫描器恰恰靠这些构造请求。暴露的收益远超「只是看看接口」。