API文档目录需实施精准访问控制：优先限制IP（allow/deny all），其次启用Basic Auth，禁止敏感文件直接访问，可结合Referer或自定义请求头校验。
对 API 文档目录（如 /docs/、/swagger/、/redoc/）实施访问控制，核心目标是：防止未授权人员浏览敏感接口说明，同时保留开发与测试团队的必要访问权限。关键不在于“完全屏蔽”，而在于“精准放行”。
限制访问来源 IP
最常用也最有效的方式，是只允许内网或特定办公出口 IP 访问文档路径：
- 在对应
location块中使用allow+deny all组合 - 支持 CIDR 表示法，例如：
allow 10.0.0.0/8;（整个内网段）、allow 203.0.113.42;（单个运维 IP） - 注意顺序：Nginx 按配置出现顺序匹配，
allow必须写在deny all之前
示例配置：
location /docs/ {<br> allow 192.168.10.0/24;<br> allow 203.0.113.42;<br> deny all;<br> alias /var/www/api-docs/;<br>}启用基础认证（Basic Auth）
适用于远程协作或需临时开放给外部测试方的场景，比单纯 IP 控制更灵活：
- 用
auth_basic开启弹窗认证，提示语可自定义（如"API Docs Access"） - 配合
auth_basic_user_file指向.htpasswd文件，该文件用htpasswd工具生成 - 建议为文档访问单独建用户（如
docs-reader），避免复用生产系统账号
示例配置：
location /swagger/ {<br> auth_basic "API Docs Access";<br> auth_basic_user_file /etc/nginx/.htpasswd-docs;<br> alias /var/www/swagger-ui/;<br>}禁止直接下载或执行敏感文件
API 文档目录常含 openapi.json、swagger.yaml 等机器可读文件，应防止被批量抓取或意外执行：
- 显式拒绝访问配置文件类扩展名：
location ~* \.(json|yaml|yml)$ { deny all; } - 若文档由静态 HTML 渲染，确保其所在目录不解析 PHP/Python 脚本（尤其当文档目录与 Web 根目录同级时）
- 可叠加
add_header X-Content-Type-Options nosniff;防止 MIME 类型嗅探绕过
结合 Referer 或请求头做轻量校验
适合已有前端管理后台且文档仅供内部系统跳转使用的场景：
- 用
if ($http_referer !~ ^https?://(admin\.example\.com|localhost:3000)) { return 403; }限制来源 - 或检查自定义请求头：
if ($http_x_internal_access != "true") { return 403; }，由上游网关统一注入 - 注意：
if在location中慎用，优先考虑用map模块预处理变量
