DRF Docs 安全指南：HIDE_DOCS 配置全解，为什么生产环境必须隐藏 API 文档

DRF Docs 安全指南：HIDE_DOCS 配置全解，为什么生产环境必须隐藏 API 文档

【免费下载链接】django-rest-framework-docsDocument Web APIs made with Django Rest Framework项目地址: https://gitcode.com/gh_mirrors/dj/django-rest-framework-docs

DRF Docs（项目名django-rest-framework-docs，pip 包名drfdocs）是一款为 Django REST Framework 接口自动生成可浏览文档的开源工具。本文带你完整理解它的核心安全配置HIDE_DOCS：如何在 3 步内完成配置、为什么生产环境必须隐藏 API 文档页面，以及新手最容易踩的 3 个坑。

DRF Docs 是什么：API 文档一键生成

DRF Docs 会自动扫描项目中所有继承自 DRFAPIView的视图，在/docs/路由（见rest_framework_docs/urls.py）下一个页面展示：

• 📋 全部接口路径（endpoint）列表
• 📋 每个接口支持的 HTTP 方法（GET / POST / PUT / PATCH / DELETE）
• 📋 请求字段名、类型与是否必填
• 📋 接口的 docstring 说明

它还提供Live API Endpoints功能，可以直接在文档页面里发起真实请求、自定义请求头并查看响应：

"文档 + 在线调试"二合一非常便利——但这也正是它在生产环境中危险的根源。

HIDE_DOCS 配置全解：工作原理

HIDE_DOCS是 DRF Docs 目前提供的核心配置项（完整说明见docs/settings.md）：

工作原理非常简单，相关代码只有两处：

• rest_framework_docs/settings.py—— 从 Django 设置的REST_FRAMEWORK_DOCS字典中读取HIDE_DOCS，未配置时默认False
• rest_framework_docs/views.py——DRFDocsView视图在返回页面数据前检查该配置，开启时直接抛出Http404

也就是说：

• False（默认）：任何人访问/docs/都能看到完整 API 文档
• True：文档页面对外整体返回404 Not Found，如同不存在

版本小知识：它曾叫 HIDDEN

早期版本中这个配置名为HIDDEN，从0.0.6 版本起更名为HIDE_DOCS（见docs/changelog.md）。如果你是从老项目升级而来，注意改对名字，否则配置会静默失效。

为什么生产环境必须隐藏 API 文档

⚠️ 对攻击者来说，一篇公开的 API 文档相当于一张"系统地图"，会暴露 4 类信息：

1. 接口全量枚举：所有 endpoint 路径一览无余，包括/accounts/reset-password/这类敏感入口
2. 请求结构泄露：字段名、字段类型、必填要求全部公开，攻击者无需探测就能"照着表单填"
3. 在线攻击面：Live API Endpoints 允许从文档页直接发请求、自定义 Authorization 头，等于给攻击者提供了一个现成的调试台
4. docstring 泄露：接口描述文本可能暴露业务逻辑与内部命名

✅ 正确的姿势是开发可见、生产隐藏。HIDE_DOCS正是为此设计：无需移除路由、无需改任何代码，一个开关就让整个文档页 404。

快速上手：3 步完成 HIDE_DOCS 配置

步骤 1：在 settings.py 中加入配置字典

打开 Django 项目的settings.py，加入：

REST_FRAMEWORK_DOCS = { 'HIDE_DOCS': True }

步骤 2：用环境变量实现多环境一键切换（推荐）

硬编码True/False意味着每切换一次环境就要改代码。官方推荐从环境变量读取：

import os REST_FRAMEWORK_DOCS = { 'HIDE_DOCS': os.environ.get('HIDE_DRFDOCS', False) }

然后在各环境独立设置HIDE_DRFDOCS（例如通过.env文件）：

• 开发环境：不设置（走默认False，文档可见）
• 生产环境：设置HIDE_DRFDOCS=True

步骤 3：验证生效

访问/docs/确认返回 404。项目自带的测试用例可直接参照：tests/tests.py中的test_index_view_docs_hidden方法，断言HIDE_DOCS=True时响应码为 404——你为自己的项目补安全测试时照抄这个写法即可。

HIDE_DOCS 配置的 3 个常见坑

📌坑 1：环境变量是字符串

os.environ.get()取到的是字符串，如果你在生产环境写了HIDE_DRFDOCS=False，字符串"False"在 Python 中是真值——文档反而被隐藏了。安全做法：只在生产设置它，且只设为True；开发环境干脆不设置。

📌坑 2：沿用旧配置名

老版本叫HIDDEN，升级后继续写旧名字不会报错，但完全不生效。认准HIDE_DOCS。

📌坑 3：误把"隐藏"当"鉴权"

HIDE_DOCS只是让文档页 404，API 端点本身依然可访问（这是正常的）。真正的访问控制要靠 DRF 自身的 authentication 与 permissions 完成——HIDE_DOCS 的定位是减少信息暴露，而非访问控制。

动手体验：运行官方 Demo 项目

git clone https://gitcode.com/gh_mirrors/dj/django-rest-framework-docs

克隆后打开仓库中的demo/目录（含demo/README.md运行说明），这是一个内置 DRF 接口的示例 Django 项目，能完整体验文档页、搜索过滤与 Live API，也方便你亲手验证HIDE_DOCS=True后的 404 效果。

小结

HIDE_DOCS 是 DRF Docs 唯一、却至关重要的安全开关：

1. ✅ 生产部署前，确保REST_FRAMEWORK_DOCS中HIDE_DOCS为True
2. ✅ 推荐用HIDE_DRFDOCS环境变量区分开发/生产环境
3. ✅ 上线后手动访问一次/docs/，确认返回 404

文档是好东西，但只该出现在它该在的地方。

【免费下载链接】django-rest-framework-docsDocument Web APIs made with Django Rest Framework项目地址: https://gitcode.com/gh_mirrors/dj/django-rest-framework-docs