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和自动文档界面中。各参数说明如下参数类型说明titlestrAPI 的标题。summarystrAPI 的简短摘要。自 OpenAPI 3.1.0、FastAPI 0.99.0 起可用。descriptionstrAPI 的简短描述支持 Markdown。versionstrAPI 的版本号指的是你应用的版本而非 OpenAPI 版本例如2.5.0。默认值为0.1.0见 applications.py。terms_of_servicestr指向 API 服务条款的 URL如提供则必须是合法 URL。contactdictAPI 的联系信息可含多个字段name联系人/组织名称str、url联系信息 URLstr必须为 URL 格式、email联系邮箱str必须为邮箱格式。license_infodictAPI 的许可证信息可含多个字段name必填许可证名称、identifierSPDX 许可证表达式str与url字段互斥。自 OpenAPI 3.1.0、FastAPI 0.99.0 起可用、url许可证 URLstr必须为 URL 格式。完整配置示例对应 tutorial001_py310.pyfrom 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( titleChimichangApp, descriptiondescription, summaryDeadpools favorite app. Nuff said., version0.0.1, terms_of_servicehttp://example.com/terms/, contact{ name: Deadpoolio the Amazing, url: http://x-force.example.com/contact/, email: dpx-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字段其值为一个 SPDXlicense_info{ name: Apache 2.0, identifier: Apache-2.0, },注意规范约定identifier与url两个字段互斥配置许可证时二者选其一即可。name字段在提供license_info时仍是必填项。三、标签Tags元数据你可以为用于分组路径操作的各个 Tag 添加额外元数据参数为openapi_tags。它接收一个列表列表中每一项是一个dict每个字典可包含name必填与你在路径操作和APIRouter的tags参数中使用的 Tag 名称相同的strdescriptionTag 的简短描述str可以包含 Markdown并在文档界面中显示externalDocs描述外部文档的dict包含description外部文档的简短描述strurl必填外部文档的 URLstr。创建标签元数据以users和items两个 Tag 为例创建元数据并传入openapi_tags参数对应 tutorial004_py310.pyfrom 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_tagstags_metadata)描述中可以使用 Markdown例如 login 会以粗体login显示fancy 会以斜体fancy显示。提示你不必为使用的所有 Tag 都添加元数据。源码文档字符串applications.py 中openapi_tags的Doc说明也确认了这一点未声明的 Tag 仍会出现在文档中只是可能被工具按随机顺序或自身逻辑排列而声明过的 Tag 会按列表顺序排列。使用你的 Tags在路径操作和APIRouter上通过tags参数为操作分配 Tagapp.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.pyfrom fastapi import FastAPI app FastAPI(openapi_url/api/v1/openapi.json)如果你希望完全禁用 OpenAPI schema 的暴露可以设置openapi_urlNone——此时所有依赖它的文档界面也会被一并禁用。这一联动逻辑在源码中有直接体现应用初始化 中/docsSwagger UI路由的注册条件是if self.openapi_url and self.docs_url/redocReDoc路由的注册条件是if self.openapi_url and self.redoc_url。也就是说只要openapi_url为None两个文档界面都会自动消失无需再手动设置docs_urlNone和redoc_urlNone。五、文档 URLdocs_url / redoc_url你可以配置内置的两个文档界面Swagger UI默认提供于/docs。可通过docs_url参数修改其 URL设置docs_urlNone可禁用它。ReDoc默认提供于/redoc。可通过redoc_url参数修改其 URL设置redoc_urlNone可禁用它。例如把 Swagger UI 配置到/documentation并同时禁用 ReDoc对应 tutorial003_py310.pyfrom fastapi import FastAPI app FastAPI(docs_url/documentation, redoc_urlNone)文档路由的注册细节从 applications.py 的路由注册代码可以看出完整机制若self.openapi_url存在会先注册一条返回openapi()JSON 的路由并显式设置include_in_schemaFalse避免文档路由自身出现在 schema 中Swagger UI 与 ReDoc 均为 HTML 路由同样include_in_schemaFalse且都基于self.openapi_url计算 schema 的openapi_url地址若应用存在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.pydescription与 Tag 描述均支持 Markdown 渲染license_info自 FastAPI 0.99.0 起支持 SPDXidentifier与url互斥openapi_tags为 Tag 提供description与externalDocs列表顺序即文档界面中的显示顺序且无需覆盖所有 Tagopenapi_url、docs_url、redoc_url控制三个端点的地址任一设置为None均可禁用对应功能且openapi_urlNone会连带禁用两个文档界面。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考