FastAPI 元数据与文档 URL 配置指南：OpenAPI 元信息、openapi_tags 与文档地址实战

FastAPI 元数据与文档 URL 配置指南：OpenAPI 元信息、openapi_tags 与文档地址实战

【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi

在 FastAPI 应用中可以配置多类元数据（metadata），用于控制自动生成的 OpenAPI 规范与交互式 API 文档（Swagger UI、ReDoc）的外观和行为。本文围绕 FastAPI 官方教程中的 Metadata 章节展开，完整覆盖title、description、license_info等 API 级元数据参数、openapi_tags标签元数据、以及openapi_url/docs_url/redoc_url文档地址配置，并结合fastapi/applications.py与fastapi/openapi/utils.py中的源码实现，说明这些参数最终如何被写入 OpenAPI schema。读完后你可以为自己的 API 完整定制文档标题、描述、联系/许可信息，并控制文档的暴露路径。

一、API 元数据（Metadata for API）

你可以在FastAPI()构造函数中设置若干字段，它们会直接体现在 OpenAPI 规范（/openapi.json）和自动文档界面中。各参数说明如下：

完整配置示例（对应 tutorial001_py310.py）：

from fastapi import FastAPI description = """ ChimichangApp API helps you do awesome stuff. 🚀 ## Items You can **read items**. ## Users You will be able to: * **Create users** (_not implemented_). * **Read users** (_not implemented_). """ app = FastAPI( title="ChimichangApp", description=description, summary="Deadpool's favorite app. Nuff said.", version="0.0.1", terms_of_service="http://example.com/terms/", contact={ "name": "Deadpoolio the Amazing", "url": "http://x-force.example.com/contact/", "email": "dp@x-force.example.com", }, license_info={ "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html", }, ) @app.get("/items/") async def read_items(): return [{"name": "Katana"}]

提示：description字段中可以书写 Markdown，并会在文档界面中渲染（例如标题## Items、加粗**read items**、列表等）。

源码视角：元数据如何进入 OpenAPI schema

从源码结构看，这些参数的处理集中在 get_openapi() 函数中：它接收title、version、summary、description、terms_of_service、contact、license_info等参数，构建info字典并映射为 OpenAPI 标准字段：

info: dict[str, Any] = {"title": title, "version": version} if summary: info["summary"] = summary if description: info["description"] = description if terms_of_service: info["termsOfService"] = terms_of_service if contact: info["contact"] = contact if license_info: info["license"] = license_info output: dict[str, Any] = {"openapi": openapi_version, "info": info}

可以看到：terms_of_service被映射为termsOfService（驼峰式，符合 OpenAPI 规范），license_info被映射为license；且所有可选字段都只在非空时写入 schema，即未设置的元数据不会出现在/openapi.json中。这些值最终由 FastAPI 应用 在启动时保存为实例属性（self.openapi_url、self.openapi_tags、self.docs_url等），并在生成 OpenAPI 路由时透传给get_openapi()。

二、许可证标识符（license identifier）

自 OpenAPI 3.1.0 和 FastAPI 0.99.0 起，license_info除了url外，还可以使用identifier字段，其值为一个 SPDX）：

license_info={ "name": "Apache 2.0", "identifier": "Apache-2.0", },

注意规范约定：identifier与url两个字段互斥，配置许可证时二者选其一即可。name字段在提供license_info时仍是必填项。

三、标签（Tags）元数据

你可以为用于分组路径操作的各个 Tag 添加额外元数据，参数为openapi_tags。它接收一个列表，列表中每一项是一个dict，每个字典可包含：

• name（必填）：与你在路径操作和APIRouter的tags参数中使用的 Tag 名称相同的str；
• description：Tag 的简短描述，str，可以包含 Markdown，并在文档界面中显示；
• externalDocs：描述外部文档的dict，包含：
  • description：外部文档的简短描述，str；
  • url（必填）：外部文档的 URL，str。

创建标签元数据

以users和items两个 Tag 为例，创建元数据并传入openapi_tags参数（对应 tutorial004_py310.py）：

from fastapi import FastAPI tags_metadata = [ { "name": "users", "description": "Operations with users. The **login** logic is also here.", }, { "name": "items", "description": "Manage items. So _fancy_ they have their own docs.", "externalDocs": { "description": "Items external docs", "url": "https://fastapi.tiangolo.com/", }, }, ] app = FastAPI(openapi_tags=tags_metadata)

描述中可以使用 Markdown：例如 "login" 会以粗体（login）显示，"fancy" 会以斜体（fancy）显示。

提示：你不必为使用的所有 Tag 都添加元数据。源码文档字符串（applications.py 中openapi_tags的Doc说明）也确认了这一点：未声明的 Tag 仍会出现在文档中，只是可能被工具按随机顺序或自身逻辑排列，而声明过的 Tag 会按列表顺序排列。

使用你的 Tags

在路径操作（和APIRouter）上通过tags参数为操作分配 Tag：

@app.get("/users/", tags=["users"]) async def get_users(): return [{"name": "Harry"}, {"name": "Ron"}] @app.get("/items/", tags=["items"]) async def get_items(): return [{"name": "wand"}, {"name": "flying broom"}]

关于 Tags 的更多用法可参考官方的路径操作配置文档中的 Tags 小节。

查看文档效果

查看文档时，所有添加的 Tag 元数据都会显示出来：

Tag 的排序

openapi_tags中各字典的顺序，同时也定义了这些 Tag 在文档界面中的显示顺序。例如users虽然按字母序排在items之后，但因为把它的元数据作为列表的第一个字典添加，所以会显示在items之前。

四、OpenAPI 规范 URL

默认情况下，OpenAPI schema 在/openapi.json路径提供（openapi_url参数默认值即"/openapi.json"，见 applications.py）。你可以用openapi_url参数修改它。例如让 schema 从/api/v1/openapi.json提供（对应 tutorial002_py310.py）：

from fastapi import FastAPI app = FastAPI(openapi_url="/api/v1/openapi.json")

如果你希望完全禁用 OpenAPI schema 的暴露，可以设置openapi_url=None——此时所有依赖它的文档界面也会被一并禁用。这一联动逻辑在源码中有直接体现：应用初始化 中，/docs（Swagger UI）路由的注册条件是if self.openapi_url and self.docs_url，/redoc（ReDoc）路由的注册条件是if self.openapi_url and self.redoc_url。也就是说，只要openapi_url为None，两个文档界面都会自动消失，无需再手动设置docs_url=None和redoc_url=None。

五、文档 URL（docs_url / redoc_url）

你可以配置内置的两个文档界面：

• Swagger UI：默认提供于/docs。
  • 可通过docs_url参数修改其 URL；
  • 设置docs_url=None可禁用它。
• ReDoc：默认提供于/redoc。
  • 可通过redoc_url参数修改其 URL；
  • 设置redoc_url=None可禁用它。

例如把 Swagger UI 配置到/documentation并同时禁用 ReDoc（对应 tutorial003_py310.py）：

from fastapi import FastAPI app = FastAPI(docs_url="/documentation", redoc_url=None)

文档路由的注册细节

从 applications.py 的路由注册代码可以看出完整机制：

1. 若self.openapi_url存在，会先注册一条返回openapi()JSON 的路由，并显式设置include_in_schema=False，避免文档路由自身出现在 schema 中；
2. Swagger UI 与 ReDoc 均为 HTML 路由（同样include_in_schema=False），且都基于self.openapi_url计算 schema 的openapi_url地址；
3. 若应用存在root_path（例如挂在子路径下部署），注册文档路由时会把root_path拼接到openapi_url之前，保证文档界面在反向代理场景下仍能正确取到 schema。

这意味着openapi_url、docs_url、redoc_url三者是相互联动的一个整体：改openapi_url时，文档界面会自动跟随新的 schema 地址；禁用openapi_url则文档界面全部失效。

小结

• API 级元数据（title、summary、description、version、terms_of_service、contact、license_info）全部写入 OpenAPI 的info块，源码实现见 fastapi/openapi/utils.py；description与 Tag 描述均支持 Markdown 渲染；
• license_info自 FastAPI 0.99.0 起支持 SPDXidentifier，与url互斥；
• openapi_tags为 Tag 提供description与externalDocs，列表顺序即文档界面中的显示顺序，且无需覆盖所有 Tag；
• openapi_url、docs_url、redoc_url控制三个端点的地址，任一设置为None均可禁用对应功能，且openapi_url=None会连带禁用两个文档界面。

【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi