使用FastAPI+Supertokens时无法访问/docs及自定义路由求助

核心问题分析 #

• localhost:3000是Supertokens预构建前端UI的端口，后端FastAPI服务运行在3001端口，因此自定义的/sessioninfo后端路由只能在3001端口访问，直接访问3000端口的该路由会因前端无对应页面显示空白。
• 3001端口访问/sessioninfo出现内部服务器错误，主要是会话验证环节配置遗漏或服务依赖未启动导致。

具体修复步骤 #

1. 完善FastAPI与Supertokens的集成配置 #

确保后端代码完整初始化Supertokens并添加必要中间件，否则verify_session()无法正常解析会话：

from fastapi import FastAPI, Depends
from supertokens_python import init, InputAppInfo
from supertokens_python.framework.fastapi import get_middleware
from supertokens_python.recipe.session import SessionContainer, verify_session, init as session_init

# 初始化Supertokens应用信息
app_info = InputAppInfo(
    app_name="demoApp",
    api_domain="http://localhost:3001",
    website_domain="http://localhost:3000",
)

# 初始化Supertokens核心及session模块
init(
    app_info=app_info,
    framework='fastapi',
    recipe_list=[
        session_init()  # 必须显式初始化session模块
    ]
)

app = FastAPI()

# 添加Supertokens中间件（处理会话凭证解析）
app.add_middleware(get_middleware())

@app.get("/sessioninfo")
async def secure_api(s: SessionContainer = Depends(verify_session())):
    return {
        "sessionHandle": s.get_handle(),
        "userId": s.get_user_id(),
        "accessTokenPayload": s.get_access_token_payload(),
    }

2. 修复/docs端点访问问题 #

FastAPI的Swagger文档属于后端服务，应访问http://localhost:3001/docs，而非前端UI的3000端口。

3. 确保服务依赖正常运行 #

• 启动Supertokens核心服务：默认监听http://localhost:3567，需确保该服务处于运行状态（可通过官方提供的启动脚本启动）。
• 验证会话有效性：访问/sessioninfo前，必须先通过3000端口的前端UI完成登录，浏览器会自动携带会话Cookie，此时后端才能通过verify_session()验证通过。

验证流程 #

1. 启动Supertokens核心服务。
2. 启动FastAPI后端（确认监听3001端口）。
3. 启动前端UI服务（确认监听3000端口）。
4. 在3000端口完成登录操作。
5. 访问http://localhost:3001/sessioninfo，应返回正常会话信息；访问http://localhost:3001/docs可查看完整API文档。

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