FastAPI schema extra如何实现换行？Swagger UI多行示例注释配置问题

Swagger UI 对字段、接口的描述文本默认采用 Markdown 渲染规则，单个换行符、单个 <br> 标签默认不会被解析为换行，是你之前测试方案失效的核心原因。

正确处理方案 #

场景1：Pydantic 模型字段的多行注释

直接使用 Python 三引号原生多行字符串，按照 Markdown 规则书写即可：

• 普通换行：行末尾加2个空格后直接回车换行
• 分段换行：两行内容之间空一行

代码示例：

from pydantic import BaseModel, Field

class Goods(BaseModel):
    name: str = Field(description="商品名称")
    desc: str = Field(
        default=None,
        description="""这是第一行描述内容（末尾加2个空格再换行）
这是普通换行后的第二行内容

这是分段后的第三行内容，和上一行之间有空行，会显示段落间距
- 支持直接插入Markdown列表
- 列表格式会正常渲染
"""
    )

场景2：接口端点的多行描述

直接把多行内容写在视图函数的文档字符串里，FastAPI 会自动读取并解析：

from fastapi import FastAPI

app = FastAPI()

@app.post("/goods/", summary="新增商品")
def add_goods():
    """
    这是接口的第一行描述
    这是普通换行后的第二行描述
    
    这是分段后的第三行描述
    1. 支持有序列表
    2. 支持*斜体*、**加粗**等所有Markdown格式
    """
    return {"status": "ok"}

排查要点 #

如果配置后还是无法正常换行，检查两个规则是否符合：

1. 不要手动添加 \n 转义字符，直接使用三引号的原生换行
2. 单个普通换行必须保证行末尾有2个空格，否则会被Markdown合并为同一行

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