『FastAPI』编写对接文档

德育处主任

发布于 2026-08-16 09:25:33

630

文章被收录于专栏：前端数据可视化前端数据可视化

点赞 + 关注 + 收藏 = 学会了

本文简介

现在流行前后端分离的开发模式，后端负责处理后台逻辑，用接口的方式和前端交互。而每个接口有什么用？如何调用？要传什么参数？没有一份接口说明书给前端的话就是后端不对了。

FastAPI 其实已经自动帮我们生成对接文档了，但有些接口对接的细节还是需要我们补充。

补充接口细节不止是为了让前端轻松点，对于后端来说也是一份良好的注释。

本文就介绍一下如何写好接口文档。

接口文档

在《『FastAPI』快速入门》介绍过，运行 FastAPI 项目后，在本地访问 http://127.0.0.1:8000/docs 或者 http://127.0.0.1:8000/redoc 都可以查看到项目对接文档。但这份默认生成的文档比较粗糙，需要我们花点小功夫润色一下。

全局说明

在实例化 FastAPI 时可以传入一些参数去润色文档。

我拿常用的参数举例说明，工友们看着代码对照截图应该能懂的。

app = FastAPI(
    title="这是整个文档的大标题",
    description="描述，对这份文档的补充说明",
    version="1.0.0", # API文档的版本号
)

接口说明

@app.get("/blogList", summary="播客列表", description="获取播客列表，无需传参进来")
def getBlogList():
    return {
        "data": {}
    }

路径参数说明

有一个 API 的功能是请求博客详情内容，接口是 /blogDetails/{blog_id}，要对 blog_id 的类型、限制、作用进行描述可以这么写。

from fastapi import FastAPI, Path

@app.get("/blogDetails/{blog_id}", summary="博客详情", description="传入博客id查看博客详情")
def getBlogDetails(
    blog_id: int = Path(..., description="博客ID", ge=10)
):
    print(blog_id)
    return {
        "data": {
            "id": blog_id
        }
    }

blog_id: int 表示这个参数是 int 型。
path(...) 表示这个参数是必传。
description 对这个参数进行描述。
ge=10 表示泽哥参数最小值是10。

查询参数说明

查询参数是 URL 中 ? 之后的一部分，通常用在过滤、分页、排序等查询操作。

使用 Query 函数定义查询参数的默认值、类型和描述。

from fastapi import FastAPI, Query

@app.get("/blogList", summary="博客列表页", description="分页查询博客列表")
def getBlogList(
    page: int = Query(1, description="页码，表示返回第几页的内容，默认值为1")
):
    print(page)
    return {
        "data": {
            "page": page
        }
    }

Query 函数用于定义查询参数说明，description 参数用于提供查询参数的描述信息。

请求体参数说明

在 FastAPI 中，可以使用 Pydantic 模型来定义请求体中的数据结构。通过定义模型的字段和描述，FastAPI 会自动在 OpenAPI 文档中展示字段的名称、类型和描述。这样，前端可以很清楚地看到请求体中的每个字段的作用。

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()

class LoginRequest(BaseModel):
    username: str = Field(..., description="用户名")
    password: str = Field(..., description="密码")

@app.post("/login")
async def login(data: LoginRequest):
    return {"message": "登录成功"}

使用 Field(..., description="...") 为每个字段添加描述。打开文档，切换到接口的 Schema 可以看到每个字段是否必填、字段类型以及这个字段的说明。

请求头参数说明

使用 Header 类来定义请求头参数，并为它们添加描述信息。

from fastapi import FastAPI, Header
from typing import Optional

app = FastAPI()

@app.get("/items/")
async def read_items(
    token: Optional[str] = Header(None, description="API 访问令牌，用于身份验证")
):
    return {"token": token}

Header 类用于定义请求头参数，description 参数提供该请求头的详细说明。

响应内容说明

使用 Response Model 和 Pydantic 模型来定义响应内容的数据结构和说明。

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()

class BlogItemResponse(BaseModel):
    blogName: str = Field(..., description="播客名称")

@app.get("/blogDetails/{blogId}", response_model=BlogItemResponse)
async def get_item(blogId: int):
    return {
        "blogName": "这是博客名"
    }

其他说明

如果以上参数说明还不够详细，你还有话想跟前端说，可以使用这种方式写备注。

from fastapi import FastAPI

app = FastAPI()

@app.get("/sayHi")
def sayHi():
    """
    主要想和你打个招呼

    - 我会传个对象给你
    - 对象里有一个 key 叫 msg
    """
    return {"msg": "雷猴"}

关闭文档

API 接口文档通常是开发时写给前端看的，真正上线后我们当然不希望别人通过 /docs 或者 /redoc 访问到我们的文档。

我们可以在实例化 FastAPI 时把文档关闭掉。

app = FastAPI(
  	docs_url = None,
  	redoc_url = None
)

此时你再访问 /docs 或者 /redoc 就会返回404。

你还可以通过 openapi_url = None 的写法代替上面两句。

app = FastAPI(
  	openapi_url = None
)

点赞 + 关注 + 收藏 = 学会了

本文参与腾讯云自媒体同步曝光计划，分享自作者个人站点/博客。

原始发表：2024-11-08，如有侵权请联系 cloudcommunity@tencent.com 删除

前端