如何基于Django权限限制用户查看部分Swagger文档且不限制endpoint使用?
Django 按用户权限过滤Swagger文档展示、不限制实际接口调用的实现方案
Swagger本身没有内置权限过滤展示能力是很多项目落地时遇到的共性需求,核心实现思路非常直接:Swagger的文档内容本质是从项目注册的路由中收集到的接口schema信息,只要在schema收集环节做一层用户权限的过滤,就能实现仅展示授权文档的效果——整个过滤逻辑完全不触碰实际的路由注册、接口权限校验流程,天然满足“不限制用户调用无文档查看权限的接口”的要求。
核心实现逻辑
所有现在主流的Django Swagger方案(drf-spectacular、drf-yasg)都支持自定义Schema生成器,你只需要在生成器的「收集全量接口端点」阶段,传入当前请求对应的登录用户,逐个判断每个接口对应的视图权限,对当前用户没有文档查看权限的端点直接从收集列表中剔除即可。
- 整个流程的过滤仅作用于Swagger文档的渲染环节,不会修改实际的路由配置、不会改动接口本身的权限校验规则
- 不管用户能不能在Swagger页面看到某个接口,只要他满足接口本身的权限要求,就可以正常发请求调用,完全不会产生访问限制
分场景适配实现
基于drf-spectacular(当前官方推荐方案)的实现
自定义继承自SchemaGenerator的生成器类,重写端点收集方法做权限过滤,示例核心代码:
from drf_spectacular.generators import SchemaGenerator from rest_framework.permissions import BasePermission class PermissionFilteredSchemaGenerator(SchemaGenerator): def get_endpoints(self, request): # 先获取全量的项目端点列表 all_endpoints = super().get_endpoints(request) valid_endpoints = [] for endpoint_path, endpoint_info in all_endpoints: view_cls = endpoint_info.get("cls") if not view_cls: valid_endpoints.append((endpoint_path, endpoint_info)) continue # 拿到视图绑定的权限类,匹配用户权限决定是否展示文档 bound_perms = getattr(view_cls, "permission_classes", []) show_to_user = all( perm().has_permission(request, view_cls) for perm in bound_perms if issubclass(perm, BasePermission) ) if show_to_user: valid_endpoints.append((endpoint_path, endpoint_info)) return valid_endpoints
最后只需要把自定义的生成器配置到SPECTACULAR_SETTINGS里,替换默认的生成器即可。
基于drf-yasg(存量老项目常用方案)的实现
逻辑和上面完全一致,自定义继承自OpenAPISchemaGenerator的生成器,重写get_endpoints方法完成相同的权限过滤逻辑,不需要改动原有路由和视图的任何配置。
落地注意事项
- 严格区分过滤环节的边界:权限校验逻辑只用于判断是否展示对应Swagger文档,千万不要把这层过滤和实际接口的权限校验逻辑耦合,避免出现“看不到文档就无法调用接口”的问题
- 权限规则可以灵活定制:你可以完全按照Django本身的权限体系来设计展示规则,比如管理员默认看全量文档、普通用户仅能看到自己有操作权限的接口模块、超管可以看到所有调试类接口,这些规则都可以在自定义生成器里灵活配置,不需要依赖Swagger的内置能力
- 可选扩展:如果有需要,还可以在同一个生成器里增加字段级的过滤,对不同权限的用户展示不同粒度的接口入参、出参字段说明,同样不影响实际接口的运行逻辑。
内容的提问来源于stack exchange,提问作者codesaurusrex
相关产品推荐
相关产品推荐

