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":