FastAPI系列15：API文档的定制和美化

在前面的内容里，我们详细讨论了FastAPI的各个方面，作为一个web框架，FastAPI却把“API”放在了名称之中，强调了它对于API的专注，而这一点可以在它的API文档定制和美化功能上得到很好的体现。

FastAPI 支持的文档规范

FastAPI 支持三种形式的自动生成 API 文档界面，基于 OpenAPI 规范（前身为 Swagger），开发者可以无需手动维护文档，大大提升开发效率和文档质量。

Swagger UI (/docs)

• 提供可交互的 API 文档界面
• 支持「Try it out」在线测试请求
• 自动读取接口信息、参数类型、示例等

ReDoc (/redoc)

• 更简洁优雅的文档样式（只读、不可测试）
• 更适合阅读文档/接口说明，不适合调试请求
• 支持嵌套结构美观展示

OpenAPI JSON (/openapi.json)

• 纯 JSON 格式，定义了 API 的结构、模型、路径、参数
• 可被工具（如 Swagger Codegen、Postman、第三方客户端）解析自动生成代码

文档全局配置

1、定义API文档的基础信息

app = FastAPI(
	# API 的标题
    title="商城后台 API",
    # Swagger 路径，可通过`docs_url=None`禁用
	docs_url="/swagger",   
	# ReDoc 路径，可通过`redoc_url=None`禁用
    redoc_url="/docs-ui",   
    # OpenAPI 描述文档路径，可通过`openapi_url=None`禁用
    openapi_url="/api/openapi.json" 
    # API 的简短摘要。
    summary="本API接口主要为商城APP提供的"
    # API 的版本。这是您自己的应用程序的版本，而不是 OpenAPI 的版本。
    version="1.0.0"
    # API 的简短描述。可以使用Markdown。
    description="包括管理用户、订单和商品的接口集合",
    # API 服务条款的 URL。如果提供，则必须是 URL。
    terms_of_service="http://example.com/terms/", 
    # 公开的 API 的联系信息。它可以包含多个字段。
    contact={ 
	    "name": "geekabc", 
	    "url": "http://geekabc.example.com/contact/", 
	    "email": "geekabc@example.com"
	}, 
	# 公开的 API 的许可证信息。它可以包含多个字段。
	license_info={ 
		"name": 
		"Apache 2.0", 
		"url": "https://www.apache.org/licenses/LICENSE-2.0.html"
	},

)

2、定义和使用接口Tag分组

tags_metadata = [{ 
		"name": "users", 
		"description": "用户管理模块", 
	}, { 
		"name": "items", 
		"description": "商品管理模块", 
		"externalDocs": { 
			"description": "外部文档说明", 
			"url": "https://fastapi.tiangolo.com/", 
		}
	}]

app = FastAPI(openapi_tags=tags_metadata)


@app.get("/users/", tags=["users"])
def get_users():
    return ["user1", "user2"]

@app.post("/items/", tags=["items"])
def create_item(item: Item):
    return item

接口文档美化

1、为接口写明 summary 和 description 描述

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/", summary="获取商品列表", description="此接口用于分页获取所有商品信息。")
def read_items():
    return [{"name": "Item1"}]

2、为接口参数写清晰的说明（含路径/查询/请求体/头部）

from fastapi import Query, Path

@app.get("/items/{item_id}")
def read_item(
    item_id: int = Path(..., title="商品ID", description="商品的唯一标识"),
    q: str = Query(None, description="搜索关键词", example="laptop")
):
    return {"item_id": item_id, "q": q}

3、为接口参数加类型注解和默认值（减少文档歧义）

def search_items(q: str = Query("", min_length=1, max_length=20, description="搜索关键词")):
    ...

4、为枚举类型接口参数写明可选值范围

from fastapi import FastAPI, Query
from enum import Enum

class ColorEnum(str, Enum):
    red = "red"
    green = "green"
    blue = "blue"

app = FastAPI()

@app.get("/items/")
def get_items(color: ColorEnum = Query(..., description="颜色选项")):
    return {"selected_color": color}

5、为请求体字段添加标题、描述、示例

from pydantic import BaseModel, Field

class Item(BaseModel):
    name: str = Field(..., title="商品名称", description="商品的名称，必填", example="MacBook Pro")
    price: float = Field(..., gt=0, description="商品价格，必须大于0", example=1999.99)

6、为请求模型中添加全局示例（多个 example）

class Item(BaseModel):
    name: str
    price: float

    class Config:
        schema_extra = {
            "examples": {
                "normal": {
                    "summary": "普通商品",
                    "value": {
                        "name": "手机",
                        "price": 1000
                    }
                },
                "discount": {
                    "summary": "打折商品",
                    "value": {
                        "name": "打折手机",
                        "price": 800
                    }
                }
            }
        }

7、自定义接口响应格式（Response Model + 响应说明）

from pydantic import BaseModel
from fastapi.responses import JSONResponse

class Result(BaseModel):
    code: int
    msg: str
    data: dict | None
    class Config:
        schema_extra = {
            "example": {
                "code": 0,
                "msg": "操作成功",
                "data": {"id": 1, "name": "Item1"}
            }
        }

@app.get("/ping", response_model=Result, summary="健康检查")
def ping():
    return {"code": 0, "msg": "pong", "data": None}