flask-frame 1.2.2__tar.gz → 1.3.0__tar.gz

{flask_frame-1.2.2/src/flask_frame.egg-info → flask_frame-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flask_frame
-Version: 1.2.2
+Version: 1.3.0
 Summary: 基于FLASK快速开发REST接口框架
 Author-email: wuhanchu <whcwuhanchu@gmail.com>
 License-Expression: MIT
@@ -32,8 +32,6 @@ Requires-Dist: psycopg2-binary==2.9.10
 Requires-Dist: rsa==4.9
 Requires-Dist: pycryptodome==3.23.0
 Requires-Dist: cryptography==46.0.5
-Requires-Dist: gunicorn==23.0.0
-Requires-Dist: gevent==24.11.1
 Requires-Dist: tenacity==9.1.2
 Requires-Dist: loguru==0.7.3
 Requires-Dist: pytz~=2025.2
@@ -51,7 +49,7 @@ Dynamic: license-file
 ### 本地开发
 
 ```bash
-pip install -e .
+pip3 install -e .
 ```
 
 ### 发布到 PyPI
@@ -85,6 +83,93 @@ nohup docker build . --force-rm=true -f docker/Dockerfile.alpine_continue -t wuh
 - `GET /debug-sentry` - 触发错误（调试 Sentry）
 - 任意接口加 `?profile` 参数可获取性能分析报告
 
+## OpenAPI 文档生成
+
+从 Flask 路由自动生成 OpenAPI 3.0 JSON，支持导入 Apifox 或通过 API 自动推送（增量同步）。
+
+```python
+from flask_frame import create_app, generate_openapi, sync_to_apifox
+
+app = create_app(config)
+
+# 生成 JSON 文件
+generate_openapi(app, title="My API", output_dir="./api_json")
+
+# 自动同步到 Apifox（支持增量）
+sync_to_apifox(app, token="afxp_xxx", project_id="xxx", title="My API")
+```
+
+获取凭据：Apifox 项目设置 → API 认证获取 Token，项目设置 → 基本信息获取项目 ID。
+
+### VS Code Task 配置
+
+在业务项目中创建 `.vscode/tasks.json`：
+
+```json
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "sync_to_apifox",
+      "type": "shell",
+      "command": "/usr/bin/python3.12",
+      "args": [
+        "script/sync_to_apifox.py",
+        "--token", "afxp_xxx",
+        "--project-id", "xxx"
+      ],
+      "group": "build",
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "focus": true,
+        "panel": "dedicated",
+        "showReuseMessage": false,
+        "clear": false
+      },
+      "problemMatcher": []
+    }
+  ]
+}
+```
+
+对应的 `script/sync_to_apifox.py`：
+
+```python
+import argparse
+from flask_frame import create_app, sync_to_apifox
+from config import config
+import module, context
+
+app = create_app(config)
+module.init_app(app)
+context.init_app(app)
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--token", required=True)
+parser.add_argument("--project-id", required=True)
+parser.add_argument("--force", action="store_true")
+args = parser.parse_args()
+
+sync_to_apifox(app, token=args.token, project_id=args.project_id, title="你的API名称", force=args.force)
+```
+
+使用 `Ctrl+Shift+B` 选择 `sync_to_apifox` 即可推送到 Apifox。
+
+视图函数的 Google 风格 docstring 会自动解析为 API 描述和参数说明：
+
+```python
+@app.route("/api/users")
+def get_users():
+    """获取用户列表
+
+    Args:
+        page (int): 页码，默认 1
+        size (int): 每页条数
+    """
+    ...
+```
+
 ## 配置项
 
 ### 基础配置
@@ -160,6 +245,7 @@ nohup docker build . --force-rm=true -f docker/Dockerfile.alpine_continue -t wuh
 ```
 src/flask_frame/
 ├── app.py                     # 应用工厂 create_app()
+├── openapi.py                 # OpenAPI 文档生成（generate_openapi）
 ├── api/                       # 请求/响应/异常处理
 │   ├── request.py             #   get_request_param(), proxy()
 │   ├── response.py            #   Response.make_flask_response()

{flask_frame-1.2.2 → flask_frame-1.3.0}/README.md

@@ -7,7 +7,7 @@
 ### 本地开发
 
 ```bash
-pip install -e .
+pip3 install -e .
 ```
 
 ### 发布到 PyPI
@@ -41,6 +41,93 @@ nohup docker build . --force-rm=true -f docker/Dockerfile.alpine_continue -t wuh
 - `GET /debug-sentry` - 触发错误（调试 Sentry）
 - 任意接口加 `?profile` 参数可获取性能分析报告
 
+## OpenAPI 文档生成
+
+从 Flask 路由自动生成 OpenAPI 3.0 JSON，支持导入 Apifox 或通过 API 自动推送（增量同步）。
+
+```python
+from flask_frame import create_app, generate_openapi, sync_to_apifox
+
+app = create_app(config)
+
+# 生成 JSON 文件
+generate_openapi(app, title="My API", output_dir="./api_json")
+
+# 自动同步到 Apifox（支持增量）
+sync_to_apifox(app, token="afxp_xxx", project_id="xxx", title="My API")
+```
+
+获取凭据：Apifox 项目设置 → API 认证获取 Token，项目设置 → 基本信息获取项目 ID。
+
+### VS Code Task 配置
+
+在业务项目中创建 `.vscode/tasks.json`：
+
+```json
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "sync_to_apifox",
+      "type": "shell",
+      "command": "/usr/bin/python3.12",
+      "args": [
+        "script/sync_to_apifox.py",
+        "--token", "afxp_xxx",
+        "--project-id", "xxx"
+      ],
+      "group": "build",
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "focus": true,
+        "panel": "dedicated",
+        "showReuseMessage": false,
+        "clear": false
+      },
+      "problemMatcher": []
+    }
+  ]
+}
+```
+
+对应的 `script/sync_to_apifox.py`：
+
+```python
+import argparse
+from flask_frame import create_app, sync_to_apifox
+from config import config
+import module, context
+
+app = create_app(config)
+module.init_app(app)
+context.init_app(app)
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--token", required=True)
+parser.add_argument("--project-id", required=True)
+parser.add_argument("--force", action="store_true")
+args = parser.parse_args()
+
+sync_to_apifox(app, token=args.token, project_id=args.project_id, title="你的API名称", force=args.force)
+```
+
+使用 `Ctrl+Shift+B` 选择 `sync_to_apifox` 即可推送到 Apifox。
+
+视图函数的 Google 风格 docstring 会自动解析为 API 描述和参数说明：
+
+```python
+@app.route("/api/users")
+def get_users():
+    """获取用户列表
+
+    Args:
+        page (int): 页码，默认 1
+        size (int): 每页条数
+    """
+    ...
+```
+
 ## 配置项
 
 ### 基础配置
@@ -116,6 +203,7 @@ nohup docker build . --force-rm=true -f docker/Dockerfile.alpine_continue -t wuh
 ```
 src/flask_frame/
 ├── app.py                     # 应用工厂 create_app()
+├── openapi.py                 # OpenAPI 文档生成（generate_openapi）
 ├── api/                       # 请求/响应/异常处理
 │   ├── request.py             #   get_request_param(), proxy()
 │   ├── response.py            #   Response.make_flask_response()

{flask_frame-1.2.2 → flask_frame-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flask_frame"
-version = "1.2.2"
+version = "1.3.0"
 description = "基于FLASK快速开发REST接口框架"
 readme = "README.md"
 license = "MIT"
@@ -24,23 +24,34 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
+    # 核心 Web 框架及扩展
     "Flask==3.1.3",
     "flask_marshmallow==1.3.0",
     "marshmallow==3.26.2",
     "marshmallow-sqlalchemy==1.4.2",
+
+    # 自动化
     "celery==5.5.1",
+
+    # 性能与监控
     "pyinstrument==5.0.1",
     "sentry_sdk==2.26.1",
+
+    # 网络与通信
     "Requests==2.32.3",
     "redis==5.2.1",
+
+    # 数据库
     "Flask_SQLAlchemy==3.1.1",
     "SQLAlchemy==2.0.40",
     "psycopg2-binary==2.9.10",
+
+    # 安全与加密
     "rsa==4.9",
     "pycryptodome==3.23.0",
     "cryptography==46.0.5",
-    "gunicorn==23.0.0",
-    "gevent==24.11.1",
+
+    # 工具库
     "tenacity==9.1.2",
     "loguru==0.7.3",
     "pytz~=2025.2",
@@ -56,4 +67,4 @@ Homepage = "https://github.com/wuhanchu/flask_frame"
 where = ["src"]
 
 [tool.setuptools.package-data]
-flask_frame = ["py.typed"]
+flask_frame = ["py.typed"]

{flask_frame-1.2.2 → flask_frame-1.3.0}/src/flask_frame/__init__.py

@@ -31,6 +31,7 @@ from .api.exception import ResourceError, CallException, BusiError
 from .schema import BaseSchema, DateTimeField
 from .annotation import deprecated, profile
 from .config import FlaskFrameConfig
+from .openapi import generate_openapi, sync_to_apifox
 
 __all__ = [
     "create_app",
@@ -45,4 +46,6 @@ __all__ = [
     "deprecated",
     "profile",
     "FlaskFrameConfig",
+    "generate_openapi",
+    "sync_to_apifox",
 ]

flask_frame-1.3.0/src/flask_frame/openapi.py

@@ -0,0 +1,383 @@
+# -*- coding: utf-8 -*-
+"""
+OpenAPI 文档生成与 Apifox 同步工具。
+从 Flask 应用的路由信息自动生成 OpenAPI 3.0 规范 JSON，可直接导入 Apifox 或通过 API 自动推送。
+
+使用示例：
+    from flask_frame import create_app
+    from flask_frame.openapi import generate_openapi, sync_to_apifox
+
+    app = create_app(config)
+
+    # 生成完整规范（返回 dict）
+    spec = generate_openapi(app, title="My API")
+
+    # 按蓝图分组生成并保存为文件
+    generate_openapi(app, title="My API", output_dir="./api_json", group_by="blueprint")
+
+    # 同步到 Apifox（支持增量同步）
+    sync_to_apifox(app, token="xxx", project_id="xxx", title="My API")
+"""
+import json
+import os
+import re
+import inspect
+import hashlib
+from typing import Any
+
+__all__ = ["generate_openapi", "sync_to_apifox"]
+
+
+def _parse_docstring(func) -> dict[str, Any]:
+    """
+    解析视图函数的 docstring，提取 summary、description、参数说明。
+
+    支持 Google 风格：
+        summary 一句话描述
+        更详细的 description
+
+        Args:
+            name (str): 参数说明
+            page (int, optional): 页码，默认 1
+
+        Returns:
+            dict: 返回说明
+
+    Returns:
+        dict: {"summary": ..., "description": ..., "params": [...]}
+    """
+    doc = inspect.getdoc(func)
+    if not doc:
+        return {"summary": "", "description": "", "params": []}
+
+    lines = doc.strip().split("\n")
+    summary = lines[0].strip()
+    description = ""
+    params = []
+
+    # 提取 Args 段落
+    in_args = False
+    for line in lines[1:]:
+        stripped = line.strip()
+
+        if stripped.lower().startswith("args:"):
+            in_args = True
+            continue
+        if in_args:
+            if stripped and not stripped.startswith(" ") and not line.startswith(" "):
+                # 遇到新的顶级段落，结束 Args
+                in_args = False
+            else:
+                # 解析参数行：name (type): description  或  name: description
+                match = re.match(
+                    r"(\w+)\s*(?:\([^)]*\))?\s*[:：]\s*(.+)", stripped
+                )
+                if match:
+                    params.append({
+                        "name": match.group(1),
+                        "description": match.group(2).strip(),
+                    })
+
+    # 非 Args 段落的非首行内容作为 description
+    desc_lines = []
+    in_args = False
+    for line in lines[1:]:
+        stripped = line.strip()
+        if stripped.lower().startswith("args:"):
+            in_args = True
+            continue
+        if stripped.lower().startswith("returns:"):
+            break
+        if not in_args and stripped:
+            desc_lines.append(stripped)
+    description = "\n".join(desc_lines)
+
+    return {"summary": summary, "description": description, "params": params}
+
+
+def _build_paths(app, filter_prefix: str | None = None) -> dict[str, dict]:
+    """
+    从 Flask app 的 url_map 构建 OpenAPI paths 对象。
+
+    Args:
+        app: Flask 应用实例。
+        filter_prefix: 路径前缀过滤，仅包含以此前缀开头的路由。
+
+    Returns:
+        dict: OpenAPI paths 字典。
+    """
+    paths: dict[str, dict] = {}
+
+    for rule in app.url_map.iter_rules():
+        # 跳过静态文件和内部路由
+        if rule.endpoint in ("static",) or rule.endpoint.startswith("flasgger"):
+            continue
+
+        path = rule.rule
+        if filter_prefix and not path.startswith(filter_prefix):
+            continue
+
+        # 将 Flask 路径参数 <name> 转为 OpenAPI {name}
+        openapi_path = re.sub(r"<(?:\w+:)?(\w+)>", r"{\1}", path)
+
+        methods = [m for m in rule.methods if m not in ("HEAD", "OPTIONS")]
+        if not methods:
+            continue
+
+        view_func = app.view_functions.get(rule.endpoint)
+        doc_info = _parse_docstring(view_func) if view_func else {}
+
+        # 从路由参数推断路径参数类型
+        path_params = []
+        for arg in rule.arguments:
+            converter = rule._converters.get(arg)
+            param_type = "string"
+            if converter:
+                type_map = {"int": "integer", "float": "number"}
+                param_type = type_map.get(getattr(converter, "type", ""), "string")
+            path_params.append({
+                "name": arg,
+                "in": "path",
+                "required": True,
+                "schema": {"type": param_type},
+            })
+
+        # 从 docstring 的 Args 段落补充 query 参数
+        query_params = []
+        for p in doc_info.get("params", []):
+            query_params.append({
+                "name": p["name"],
+                "in": "query",
+                "required": False,
+                "schema": {"type": "string"},
+                "description": p["description"],
+            })
+
+        parameters = path_params + query_params
+
+        path_item: dict[str, Any] = {}
+        for method in methods:
+            operation: dict[str, Any] = {
+                "summary": doc_info.get("summary", f"{method} {openapi_path}"),
+                "tags": [_get_tag(rule.endpoint)],
+                "responses": {
+                    "200": {"description": "成功"},
+                    "500": {"description": "服务器错误"},
+                },
+            }
+            if doc_info.get("description"):
+                operation["description"] = doc_info["description"]
+            if parameters:
+                operation["parameters"] = parameters
+
+            path_item[method.lower()] = operation
+
+        paths[openapi_path] = path_item
+
+    return paths
+
+
+def _get_tag(endpoint: str) -> str:
+    """从 endpoint 名称提取 tag（取第一段作为分组）。"""
+    parts = endpoint.split(".")
+    return parts[0] if len(parts) > 1 else "default"
+
+
+def generate_openapi(
+    app,
+    title: str = "API",
+    version: str = "1.0.0",
+    description: str = "",
+    filter_prefix: str | None = None,
+    group_by: str | None = None,
+    output_dir: str | None = None,
+) -> dict | dict[str, dict]:
+    """
+    从 Flask 应用生成 OpenAPI 3.0 规范。
+
+    Args:
+        app: 已初始化路由的 Flask 应用实例。
+        title: API 标题。
+        version: API 版本号。
+        description: API 描述。
+        filter_prefix: 仅生成以此路径前缀开头的路由（如 "/api/v1"）。
+        group_by: 分组方式。"blueprint" 按蓝图前缀拆分为多个文件，None 生成单个文件。
+        output_dir: 输出目录。指定时自动保存 JSON 文件。
+
+    Returns:
+        单文件模式返回 dict（OpenAPI 3.0 规范）。
+        分组模式返回 dict[str, dict]（键为蓝图名，值为规范）。
+    """
+    base_spec = {
+        "openapi": "3.0.0",
+        "info": {
+            "title": title,
+            "version": version,
+        },
+        "paths": {},
+    }
+    if description:
+        base_spec["info"]["description"] = description
+
+    if group_by == "blueprint":
+        # 按蓝图分组
+        tag_groups: dict[str, dict[str, dict]] = {}
+        all_paths = _build_paths(app, filter_prefix)
+
+        for path, path_item in all_paths.items():
+            for method, operation in path_item.items():
+                tag = operation.get("tags", ["default"])[0]
+                if tag not in tag_groups:
+                    tag_groups[tag] = {}
+                if path not in tag_groups[tag]:
+                    tag_groups[tag][path] = {}
+                tag_groups[tag][path][method] = operation
+
+        result = {}
+        for tag, paths in tag_groups.items():
+            spec = {**base_spec, "info": {**base_spec["info"], "title": f"{title} - {tag}"}, "paths": paths}
+            result[tag] = spec
+
+        if output_dir:
+            os.makedirs(output_dir, exist_ok=True)
+            for tag, spec in result.items():
+                file_path = os.path.join(output_dir, f"{tag}.json")
+                with open(file_path, "w", encoding="utf-8") as f:
+                    json.dump(spec, f, ensure_ascii=False, indent=2)
+
+        return result
+    else:
+        # 单文件模式
+        spec = {**base_spec, "paths": _build_paths(app, filter_prefix)}
+
+        if output_dir:
+            os.makedirs(output_dir, exist_ok=True)
+            file_path = os.path.join(output_dir, "openapi.json")
+            with open(file_path, "w", encoding="utf-8") as f:
+                json.dump(spec, f, ensure_ascii=False, indent=2)
+
+        return spec
+
+
+def _compute_hash(data: Any) -> str:
+    """计算数据的 SHA-256 哈希，用于增量同步对比。"""
+    normalized = json.dumps(data, sort_keys=True, ensure_ascii=False)
+    return hashlib.sha256(normalized.encode("utf-8")).hexdigest()
+
+
+def _load_snapshot(snapshot_dir: str) -> dict:
+    """加载增量同步快照。"""
+    hash_path = os.path.join(snapshot_dir, "path_hashes.json")
+    if os.path.exists(hash_path):
+        with open(hash_path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    return {}
+
+
+def _save_snapshot(snapshot_dir: str, data: dict) -> None:
+    """保存增量同步快照。"""
+    os.makedirs(snapshot_dir, exist_ok=True)
+    hash_path = os.path.join(snapshot_dir, "path_hashes.json")
+    with open(hash_path, "w", encoding="utf-8") as f:
+        json.dump(data, f, ensure_ascii=False, indent=2)
+
+
+def sync_to_apifox(
+    app,
+    token: str,
+    project_id: str,
+    title: str = "API",
+    version: str = "1.0.0",
+    description: str = "",
+    filter_prefix: str | None = None,
+    snapshot_dir: str | None = None,
+    force: bool = False,
+) -> bool:
+    """
+    生成 OpenAPI 规范并同步到 Apifox，支持增量同步。
+
+    Args:
+        app: 已初始化路由的 Flask 应用实例。
+        token: Apifox API Token（从 Apifox 项目设置 → API 认证 获取）。
+        project_id: Apifox 项目 ID（从项目设置 → 基本信息获取）。
+        title: API 标题。
+        version: API 版本号。
+        description: API 描述。
+        filter_prefix: 仅同步以此路径前缀开头的路由。
+        snapshot_dir: 增量快照目录，默认为当前工作目录下的 .sync_snapshot。
+        force: 强制全量同步，忽略增量检测。
+
+    Returns:
+        bool: 同步是否成功。
+    """
+    import requests
+
+    spec = generate_openapi(app, title=title, version=version, description=description, filter_prefix=filter_prefix)
+    paths = spec.get("paths", {})
+
+    # 增量同步检测
+    if snapshot_dir is None:
+        snapshot_dir = os.path.join(os.getcwd(), ".sync_snapshot")
+
+    if not force:
+        last_hashes = _load_snapshot(snapshot_dir)
+        new_hashes = {}
+        changed_paths = {}
+
+        for path, methods in paths.items():
+            h = _compute_hash(methods)
+            new_hashes[path] = h
+            if last_hashes.get(path) != h:
+                changed_paths[path] = methods
+
+        deleted = set(last_hashes.keys()) - set(paths.keys())
+
+        if not changed_paths and not deleted:
+            print("API 无变化，跳过同步")
+            return True
+
+        print(f"检测到 {len(changed_paths)} 个接口变更" + (f"，{len(deleted)} 个接口删除" if deleted else ""))
+        push_spec = {**spec, "paths": changed_paths}
+        incremental = True
+    else:
+        push_spec = spec
+        incremental = False
+        new_hashes = {p: _compute_hash(m) for p, m in paths.items()}
+
+    # 调用 Apifox API
+    url = f"https://api.apifox.com/v1/projects/{project_id}/import-openapi?locale=zh-CN"
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "X-Apifox-Api-Version": "2024-03-28",
+        "Content-Type": "application/json",
+    }
+    payload = {
+        "input": json.dumps(push_spec, ensure_ascii=False),
+        "options": {
+            "endpointOverwriteBehavior": "OVERWRITE_EXISTING",
+            "schemaOverwriteBehavior": "OVERWRITE_EXISTING",
+            "updateFolderOfChangedEndpoint": True,
+            "deleteUnmatchedResources": not incremental,
+        },
+    }
+
+    try:
+        response = requests.post(url, headers=headers, json=payload, timeout=60)
+        if response.status_code == 200:
+            result = response.json()
+            counters = result.get("data", {}).get("counters", {})
+            created = counters.get("endpointCreated", 0)
+            updated = counters.get("endpointUpdated", 0)
+            failed = counters.get("endpointFailed", 0)
+            print(f"同步成功！创建: {created}, 更新: {updated}, 失败: {failed}")
+
+            # 保存快照
+            _save_snapshot(snapshot_dir, new_hashes)
+            return True
+        else:
+            print(f"同步失败，状态码: {response.status_code}")
+            print(f"错误信息: {response.text}")
+            return False
+    except requests.exceptions.RequestException as e:
+        print(f"网络请求失败: {e}")
+        return False

{flask_frame-1.2.2 → flask_frame-1.3.0/src/flask_frame.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flask_frame
-Version: 1.2.2
+Version: 1.3.0
 Summary: 基于FLASK快速开发REST接口框架
 Author-email: wuhanchu <whcwuhanchu@gmail.com>
 License-Expression: MIT
@@ -32,8 +32,6 @@ Requires-Dist: psycopg2-binary==2.9.10
 Requires-Dist: rsa==4.9
 Requires-Dist: pycryptodome==3.23.0
 Requires-Dist: cryptography==46.0.5
-Requires-Dist: gunicorn==23.0.0
-Requires-Dist: gevent==24.11.1
 Requires-Dist: tenacity==9.1.2
 Requires-Dist: loguru==0.7.3
 Requires-Dist: pytz~=2025.2
@@ -51,7 +49,7 @@ Dynamic: license-file
 ### 本地开发
 
 ```bash
-pip install -e .
+pip3 install -e .
 ```
 
 ### 发布到 PyPI
@@ -85,6 +83,93 @@ nohup docker build . --force-rm=true -f docker/Dockerfile.alpine_continue -t wuh
 - `GET /debug-sentry` - 触发错误（调试 Sentry）
 - 任意接口加 `?profile` 参数可获取性能分析报告
 
+## OpenAPI 文档生成
+
+从 Flask 路由自动生成 OpenAPI 3.0 JSON，支持导入 Apifox 或通过 API 自动推送（增量同步）。
+
+```python
+from flask_frame import create_app, generate_openapi, sync_to_apifox
+
+app = create_app(config)
+
+# 生成 JSON 文件
+generate_openapi(app, title="My API", output_dir="./api_json")
+
+# 自动同步到 Apifox（支持增量）
+sync_to_apifox(app, token="afxp_xxx", project_id="xxx", title="My API")
+```
+
+获取凭据：Apifox 项目设置 → API 认证获取 Token，项目设置 → 基本信息获取项目 ID。
+
+### VS Code Task 配置
+
+在业务项目中创建 `.vscode/tasks.json`：
+
+```json
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "sync_to_apifox",
+      "type": "shell",
+      "command": "/usr/bin/python3.12",
+      "args": [
+        "script/sync_to_apifox.py",
+        "--token", "afxp_xxx",
+        "--project-id", "xxx"
+      ],
+      "group": "build",
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "focus": true,
+        "panel": "dedicated",
+        "showReuseMessage": false,
+        "clear": false
+      },
+      "problemMatcher": []
+    }
+  ]
+}
+```
+
+对应的 `script/sync_to_apifox.py`：
+
+```python
+import argparse
+from flask_frame import create_app, sync_to_apifox
+from config import config
+import module, context
+
+app = create_app(config)
+module.init_app(app)
+context.init_app(app)
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--token", required=True)
+parser.add_argument("--project-id", required=True)
+parser.add_argument("--force", action="store_true")
+args = parser.parse_args()
+
+sync_to_apifox(app, token=args.token, project_id=args.project_id, title="你的API名称", force=args.force)
+```
+
+使用 `Ctrl+Shift+B` 选择 `sync_to_apifox` 即可推送到 Apifox。
+
+视图函数的 Google 风格 docstring 会自动解析为 API 描述和参数说明：
+
+```python
+@app.route("/api/users")
+def get_users():
+    """获取用户列表
+
+    Args:
+        page (int): 页码，默认 1
+        size (int): 每页条数
+    """
+    ...
+```
+
 ## 配置项
 
 ### 基础配置
@@ -160,6 +245,7 @@ nohup docker build . --force-rm=true -f docker/Dockerfile.alpine_continue -t wuh
 ```
 src/flask_frame/
 ├── app.py                     # 应用工厂 create_app()
+├── openapi.py                 # OpenAPI 文档生成（generate_openapi）
 ├── api/                       # 请求/响应/异常处理
 │   ├── request.py             #   get_request_param(), proxy()
 │   ├── response.py            #   Response.make_flask_response()

{flask_frame-1.2.2 → flask_frame-1.3.0}/src/flask_frame.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 src/flask_frame/__init__.py
 src/flask_frame/app.py
 src/flask_frame/config.py
+src/flask_frame/openapi.py
 src/flask_frame/permission_context.py
 src/flask_frame/py.typed
 src/flask_frame.egg-info/PKG-INFO

{flask_frame-1.2.2 → flask_frame-1.3.0}/src/flask_frame.egg-info/requires.txt

@@ -13,8 +13,6 @@ psycopg2-binary==2.9.10
 rsa==4.9
 pycryptodome==3.23.0
 cryptography==46.0.5
-gunicorn==23.0.0
-gevent==24.11.1
 tenacity==9.1.2
 loguru==0.7.3
 pytz~=2025.2