FastAPI路由置于main函数或__name__块中引发Swagger UI报错问题

为什么你的写法会导致Swagger报错？ #

FastAPI启动时会扫描模块中的路由装饰器（比如@app.get）生成OpenAPI规范，以此提供Swagger UI。但你的代码把路由定义放在了def main()函数内部或者if __name__ == '__main__'代码块中：

• 用uvicorn等服务器启动应用时（比如uvicorn main:app --reload），uvicorn会导入你的模块，此时模块的__name__不是__main__，所以if __name__ == '__main__'里的代码不会执行，路由根本没被注册。
• 放在main()函数里但只在__main__块调用，模块导入阶段main()没执行，同样不会注册路由。

最终FastAPI找不到任何路由，就会出现No operations defined in spec!的报错。

正确的写法 #

方案一：全局定义路由（FastAPI推荐写法） #

把路由直接定义在全局作用域，模块加载时就会注册路由，不管是uvicorn导入还是直接运行脚本都能识别：

from fastapi import FastAPI
app = FastAPI()

@app.get("/fast")
async def fast(target: str, input_time: float):
    return (target, input_time)

if __name__ == '__main__':
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

方案二：用APIRouter封装路由逻辑 #

如果希望把路由逻辑封装起来，可使用APIRouter，在模块加载时完成路由注册：

from fastapi import FastAPI, APIRouter

def setup_routes():
    router = APIRouter()
    
    @router.get("/fast")
    async def fast(target: str, input_time: float):
        return (target, input_time)
    
    return router

app = FastAPI()
# 模块加载时就执行路由注册
app.include_router(setup_routes())

if __name__ == '__main__':
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

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