17_AI智能体开发架构搭建之Flask集成swagger在线文档实践

from flask import Flask, request, jsonify
from flask_restx import Api, Resource
from app.utils import config, setup_logging

def create_app():
    """创建并配置Flask应用"""
    app = Flask(__name__)

    # 初始化日志配置
    logger = setup_logging()

    # 配置应用
    app.config.update(
        DEBUG=config.DEBUG,
        SECRET_KEY=config.SECRET_KEY if hasattr(config, 'SECRET_KEY') else 'dev',
        PROPAGATE_EXCEPTIONS=True,
        RESTX_MASK_SWAGGER=False  # 禁用敏感数据屏蔽
    )

    # 创建 RESTX API 实例
    api = Api(
        app,
        version='1.0',
        title='FlyOSS Assistant API',
        description='FlyOSS Assistant API 文档',
        doc='/docs',  # 文档访问路径
        default='API',
        default_label='主要 API 操作',
        contact='flyoss-ai@flyoss.com',
        contact_url='https://www.flyoss.com',
    )

    # 关键修复：确保根路由正确注册，并指定唯一的端点名称
    @app.route('/index', endpoint='homepage')
    def home():
        """应用首页"""
        return {
            "name": "FlyOSS Assistant",
            "version": "0.1.0",
            "status": "running"
        }

    # 使用装饰器注册API根路由
    @api.route('/api', endpoint='api_root')
    class ApiRootResource(Resource):
        @api.doc('api_root')
        @api.response(200, 'API状态信息')
        def get(self):
            """API根端点"""
            return {
                "api_version": "1.0",
                "endpoints": {
                    "documentation": "/docs"
                }
            }

    @app.before_request
    def before_request():
        """请求前处理"""
        logger.info(f"收到请求: {request.method} {request.path}")

    @app.after_request
    def after_request(response):
        """请求后处理"""
        logger.info(f"请求完成: {request.method} {request.path} - 状态码: {response.status_code}")
        return response

    # 全局错误处理
    @app.errorhandler(404)
    def handle_404(error):
        """处理404错误"""
        return jsonify({
            "error": "资源未找到",
            "message": f"请求的路径 {request.path} 不存在",
            "available_endpoints": {
                "homepage": "/index",
                "api_root": "/api",
                "documentation": "/docs"
            }
        }), 404

    @app.errorhandler(500)
    def handle_500(error):
        """处理500错误"""
        logger.error(f"服务器内部错误: {str(error)}")
        return jsonify({
            "error": "服务器内部错误",
            "message": "请稍后再试或联系管理员"
        }), 500

    @app.errorhandler(Exception)
    def handle_exception(error):
        """全局异常处理"""
        logger.error(f"未处理的异常: {str(error)}")
        return jsonify({
            "error": "服务器内部错误",
            "message": str(error)
        }), 500

    # 打印所有注册的路由用于调试
    logger.info("应用已注册的路由:")
    for rule in app.url_map.iter_rules():
        logger.info(f"  {rule} - 端点: {rule.endpoint}")

    return app

对 main.py 类进行改造，删除以下代码

复制代码

from flask import Flask

# 创建Flask应用实例并转换为ASGI应用
flask_app = Flask(__name__)

2.2 精简的启动器：关注点分离

复制代码

import uvicorn
from asgiref.wsgi import WsgiToAsgi
from app import create_app
from app.utils import config
from app.utils import setup_logging

# 初始化日志配置
logger = setup_logging()

def create_app_instance():
    """创建应用实例"""
    return create_app()

# 创建Flask应用实例并转换为ASGI应用
flask_app = create_app_instance()
app = WsgiToAsgi(flask_app)

def run_server():
    """运行应用服务器"""
    # print(f"启动服务器: {config.SERVER_HOST}:{config.SERVER_PORT}")
    logger.info(f"启动服务器: {config.SERVER_HOST}:{config.SERVER_PORT}")

    # 根据环境选择应用加载方式
    if config.DEBUG:
        # DEBUG模式使用字符串加载支持热重载
        app_to_run = "app.main:app"
    else:
        # 生产模式直接使用应用实例
        app_to_run = app

    # 使用 Uvicorn 运行 ASGI 应用
    uvicorn.run(
        app=app_to_run,
        host=config.SERVER_HOST,
        port=config.SERVER_PORT,
        reload=config.DEBUG,
        workers=1 if config.DEBUG else 4
    )

if __name__ == "__main__":
    run_server()

三、部署和验证

3.1 启动应用

复制代码

# 开发环境启动
poetry run python app/main.py

3.2 访问验证

应用主页：

复制代码

http://localhost:8000/index

Swagger文档：

复制代码

http://localhost:8000/docs

四、架构优势总结

在现代化API开发中，文档与代码的同步更新是一个永恒的挑战，通过Flask-RESTX构建自文档化的API服务。

通过这种设计，我们实现了：

关注点分离：应用创建与启动逻辑解耦
自文档化API：代码即文档，自动同步更新
类型安全：请求/响应模型的严格验证
生产就绪：错误处理、日志、安全头完备
开发体验：热重载、Swagger UI测试界面
可扩展性：命名空间支持模块化开发

API设计黄金法则：

一致性：保持URL结构和命名约定一致
可发现性：提供清晰的文档和示例
错误处理：返回有意义的错误信息
版本控制：为API演进做好准备
安全性：实施适当的认证和授权

记住，好的API设计不仅仅是技术实现，更是对开发者体验的深度思考。投资时间在设计良好的API上，将在整个项目生命周期中带来丰厚的回报。