非RESTful Flask应用中如何用OAuth2配置Swagger文档鉴权

项目基础环境说明 #

当前项目未使用Flask-RESTful架构，已通过get_swaggerui_blueprint生成Swagger UI蓝图并完成注册，可正常加载swagger.json展示全量接口文档，原有核心注册代码如下：

flask_app.register_blueprint(
    get_swaggerui_blueprint(
        SWAGGER_URL,
        DOC_URL,
        config={'app_name': "Seans-Python-Flask-REST-Boilerplate"}
    ),
    url_prefix=SWAGGER_URL
)

一、swagger.json 适配OAuth2鉴权的调整规则 #

完全遵循OpenAPI 2.0规范调整配置，无需改动原有接口路径、参数定义部分，仅在根节点新增对应鉴权配置块即可：

• 在swagger.json的根层级（与swagger、info、paths字段同级）新增securityDefinitions配置，声明OAuth2的鉴权规则，示例配置如下：

{
  "swagger": "2.0",
  "info": {
    "title": "项目接口文档",
    "version": "1.0.0"
  },
  "securityDefinitions": {
    "OAuth2DocAuth": {
      "type": "oauth2",
      "flow": "accessCode",
      "authorizationUrl": "你的OAuth服务端授权端点地址",
      "tokenUrl": "你的OAuth服务端令牌获取端点地址",
      "scopes": {
        "read:docs": "Swagger文档查看权限"
      }
    }
  },
  "security": [
    {
      "OAuth2DocAuth": ["read:docs"]
    }
  ],
  "paths": {}
}

• 配置时可根据实际使用的OAuth授权模式，调整flow字段为clientCredentials、implicit等适配值，Swagger UI前端会自动根据配置生成「Authorize」授权按钮，用户点击后将按照流程完成授权，获取的access_token会自动在后续接口调试请求中携带，无需额外开发前端交互逻辑。
• 如果仅需要限制Swagger文档页面的访问权限，不需要给所有业务接口绑定全局鉴权，可直接删除上述security全局配置块，仅保留securityDefinitions配置即可，授权按钮依然可正常展示。

二、Swagger UI 蓝图注册环节的鉴权补充（原生Flask实现，无Flask-RESTful依赖） #

get_swaggerui_blueprint生成的蓝图本质是一组注册到Flask应用的普通路由，不需要修改蓝图内部源码，仅需在注册流程中补充两层逻辑即可完成访问限制：

1. 编写通用OAuth2鉴权装饰器 #

基于Flask原生会话、请求上下文实现权限校验逻辑，示例代码：

from functools import wraps
from flask import redirect, session

def oauth2_doc_required(f):
    @wraps(f)
    def decorated(*args, **kwargs):
        # 校验会话中是否存储了有效访问令牌
        valid_token = session.get('swagger_oauth_token')
        if not valid_token:
            # 未鉴权时重定向到OAuth授权端点，带上Swagger页面的回调地址
            redirect_url = (
                f"{OAuth服务端授权端点}?response_type=code"
                f"&redirect_uri={当前Swagger页面完整地址}"
                f"&client_id=你的OAuth客户端ID&scope=read:docs"
            )
            return redirect(redirect_url)
        return f(*args, **kwargs)
    return decorated

2. 给Swagger蓝图下的所有路由绑定鉴权装饰器 #

原有蓝图注册代码保持核心逻辑不变，注册完成后遍历应用的视图函数列表，筛选出属于Swagger蓝图的所有路由，统一绑定鉴权装饰器即可：

# 原有蓝图注册逻辑保留
swagger_blueprint = get_swaggerui_blueprint(
    SWAGGER_URL,
    DOC_URL,
    config={'app_name': "Seans-Python-Flask-REST-Boilerplate"}
)
flask_app.register_blueprint(swagger_blueprint, url_prefix=SWAGGER_URL)

# 补充逻辑：统一绑定鉴权
for endpoint_name, view_func in flask_app.view_functions.items():
    # 筛选属于Swagger蓝图的所有视图函数
    if endpoint_name.startswith(f"{swagger_blueprint.name}."):
        # 替换原有视图为带鉴权校验的版本
        flask_app.view_functions[endpoint_name] = oauth2_doc_required(view_func)

配套补充实现 #

• 需要额外新增一个普通的Flask路由作为OAuth2授权回调地址，接收授权码、向OAuth服务端换取访问令牌并存储到用户会话，校验完成后重定向回原Swagger文档页面即可，全程不需要依赖Flask-RESTful组件。
• 若不想遍历视图函数绑定装饰器，也可通过蓝图自带的before_request钩子，在请求进入Swagger路由前统一做权限校验，效果完全一致。

内容的提问来源于stack exchange，提问作者adekability