FastAPI自动生成文档不显示接口参数且格式异常问题咨询

一、修复接口显示“无参数”的问题 #

出现这个问题通常是因为请求模型的定义或绑定方式不符合FastAPI的要求，按以下步骤调整：

1. 确保模型继承BaseModel
   你的RephrasingRequest必须继承自pydantic.BaseModel，否则FastAPI无法识别它作为请求体模型：

   from pydantic import BaseModel
   
   class RephrasingRequest(BaseModel):
       text: str
       style: str = "formal"
   

2. 正确在接口函数中接收模型参数
   直接在函数参数中声明模型类型，FastAPI会自动将其识别为请求体参数：

   from fastapi import FastAPI
   
   app = FastAPI()
   
   @app.post("/rephrase")
   def rephrase(request: RephrasingRequest):
       return {"rephrased_text": f"Rephrased: {request.text} (style: {request.style})"}
   

   如果接口同时有查询参数和请求体参数，需要用Body显式标记模型参数：

   from fastapi import Body, Query
   
   @app.post("/rephrase")
   def rephrase(request: RephrasingRequest = Body(...), language: str = Query("en")):
       # 业务逻辑处理
       pass
   

二、修复文档字符串格式化问题 #

FastAPI支持Markdown格式的文档字符串，按规范编写即可让SwaggerUI正确渲染：

@app.post("/rephrase")
def rephrase(request: RephrasingRequest):
    """
    文本改写接口

    ### 请求体参数
    - **text**: 需要改写的原始文本（必填）
    - **style**: 改写风格，可选值为`formal`/`casual`，默认值`formal`

    ### 返回结果
    返回包含改写后文本的JSON对象，键为`rephrased_text`
    """
    return {"rephrased_text": f"Rephrased: {request.text} (style: {request.style})"}

验证调整效果 #

启动FastAPI应用后访问http://localhost:8000/docs，查看/rephrase接口：

• 会显示完整的请求体参数表单（包含text和style字段）
• 文档字符串中的Markdown内容会被解析为格式化的说明文本

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