FastAPI中如何让Swagger UI正确展示同时返回JSON和二进制文件的接口并修复嵌套序列化器显示异常

我来帮你搞定这个Swagger UI的展示问题～

咱们先分析下为啥嵌套的ReportItemSerializer会显示成string：你在responses里手动调用了PaginatedReportItemsSerializer.schema(ref_template=...)来生成JSON schema，这种方式不会自动把嵌套的ReportItemSerializer注册到OpenAPI的components/schemas里，Swagger找不到对应的模型定义，就只能默认显示成string了。

解决方法很简单，改用FastAPI原生的方式指定JSON响应的schema，让它自动帮我们处理所有嵌套模型的注册。直接修改@router.get里的responses配置就行，具体代码如下：

@router.get(
    "/orders/report",
    responses={
        200: {
            "description": "Return report",
            "content": {
                "application/json": {
                    # 这里直接用model参数，FastAPI会自动注册所有嵌套模型
                    "model": PaginatedReportItemsSerializer
                },
                "application/octet-stream": {
                    "description": "Excel file (XLSX) containing the report"
                }
            },
        },
    }
)
async def get_report():
    # 这里可以根据请求的Accept头来返回对应内容
    # 示例逻辑：
    # from fastapi import Request, FileResponse
    # accept_header = request.headers.get("Accept", "")
    # if "application/json" in accept_header:
    #     return PaginatedReportItemsSerializer(count=0, results=[])
    # else:
    #     return FileResponse("report.xlsx", media_type="application/octet-stream", filename="report.xlsx")
    pass

关键修改说明： #

• 移除了手动调用schema(ref_template=...)的代码，换成"model": PaginatedReportItemsSerializer
• FastAPI会自动把PaginatedReportItemsSerializer和它嵌套的ReportItemSerializer都注册到OpenAPI的components/schemas中
• Swagger UI现在能正确识别嵌套的模型结构，不会再显示成string了

这样修改后，你再打开Swagger UI，就能看到results字段下正确展示ReportItemSerializer的所有属性了，同时也保留了二进制文件的响应类型配置。

备注：内容来源于stack exchange，提问作者Альберт Александров