FastAPI 擴展 OpenAPI自定義 /openapi.json 生成流程的完整指南【免費下載鏈接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production項目地址: https://gitcode.com/GitHub_Trending/fa/fastapi導讀本文圍繞 FastAPI 中如何修改自動生成的 OpenAPI Schema 展開先剖析/openapi.json的默認生成鏈路.openapi()→.openapi_schema緩存 →fastapi.openapi.utils.get_openapi再以“給 ReDoc 文檔注入自定義 Logo”為例演示如何用同一個工具函數重新生成 Schema、按需覆蓋字段并緩存與替換默認方法。讀完本文你將能夠在不改動框架源碼的前提下為任何 FastAPI 應用定制 OpenAPI 輸出例如注入廠商擴展、調整info元數據、控制servers與tags等。默認的 OpenAPI 生成流程The normal process每一個FastAPI應用實例都帶有一個.openapi()方法它負責返回應用的 OpenAPI Schema。默認流程如下在創建應用對象時setup()階段FastAPI 會為/openapi.json或你在openapi_url中配置的其他路徑注冊一個路徑操作path operation見 applications.py。該路徑操作只是把應用.openapi()方法的返回值包裝成JSONResponse返回并在存在反向代理root_path時自動補充servers前綴。默認的.openapi()方法先檢查屬性.openapi_schema是否已有內容有則直接返回沒有則調用fastapi.openapi.utils.get_openapi生成并把結果緩存到.openapi_schema。從源碼看這一緩存并不是無條件的applications.py中.openapi()會比對路由版本self.router._get_routes_version()只有「緩存為空」或「路由版本已變化」時才重新生成applications.py。也就是說即使你注冊了新路由下一次請求/openapi.json時 Schema 也會自動刷新緩存始終與當前路由保持一致。get_openapi()的關鍵參數get_openapi()定義在 utils.py其核心參數如下參數說明默認值titleOpenAPI 標題顯示在文檔中必填versionAPI 版本例如2.5.0必填openapi_version使用的 OpenAPI 規范版本3.1.0最新summaryAPI 的簡短摘要NonedescriptionAPI 描述可包含 Markdown會渲染在文檔中Noneroutes應用路由取自app.routes用于收集已注冊的路徑操作含被 include 的 Router必填webhooksWebhook 路由取自app.webhooks.routesNonetags頂層tags數組NoneserversOpenAPIservers服務器列表Noneterms_of_service服務條款 URL寫入info.termsOfServiceNonecontact聯系人信息寫入info.contactNonelicense_info許可證信息寫入info.licenseNoneseparate_input_output_schemas是否為輸入/輸出模型生成獨立的 SchemaTrueexternal_docs外部文檔鏈接寫入頂層externalDocsNone技術細節tipapp.routes是更低層的路由樹其中可能包含 FastAPI 為被 include 的 Router 內部使用的路由候選route candidates并非只有最終的APIRoute對象。你仍然可以直接把app.routes傳給get_openapi()——FastAPI 會遍歷這棵路由樹收集真正生效的路徑操作。注意notesummary參數需要 OpenAPI 3.1.0 及以上版本并由 FastAPI 0.99.0 及以上版本支持。get_openapi()內部的組裝邏輯utils.py大致為先構建info對象title/version必填summary、description、termsOfService、contact、license按需寫入再遍歷路由收集paths、securitySchemes與組件定義最后把paths、webhooks、tags、externalDocs等組裝成完整字典經jsonable_encoder(OpenAPI(**output))序列化后返回。覆蓋默認值注入 ReDoc 的自定義 Logo 擴展理解了默認流程后就可以用同一個工具函數重新生成 Schema并覆蓋其中任意部分。官方示例以 ReDoc 的x-logo廠商擴展為例為文檔頁注入自定義 Logo。第一步照常編寫 FastAPI 應用先按平時的習慣寫好整個應用例如在 tutorial001_py310.py 中定義一個GET /items/接口from fastapi import FastAPI from fastapi.openapi.utils import get_openapi app FastAPI() app.get(/items/) async def read_items(): return [{name: Foo}]第二步生成 OpenAPI Schema定義一個custom_openapi()函數在其中調用同一個工具函數生成 Schemadef custom_openapi(): if app.openapi_schema: return app.openapi_schema openapi_schema get_openapi( titleCustom title, version2.5.0, summaryThis is a very custom OpenAPI schema, descriptionHeres a longer description of the custom **OpenAPI** schema, routesapp.routes, ) ...注意這里重寫了title、version、summary、description你可以按需傳入前面表格中的任意參數例如servers[{url: https://api.example.com}]或tags[{name: items, description: Item operations}]。第三步修改 OpenAPI Schemaget_openapi()返回的是普通字典直接操作即可。這里在info對象上加入x-logo擴展讓 ReDoc 顯示自定義 Logoopenapi_schema[info][x-logo] { url: https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png }x-logo是 ReDoc 的廠商擴展vendor extensionOpenAPI 規范允許所有x-前綴的字段存在因此這種覆蓋方式是規范兼容的。你同樣可以擴展其他任何info子字段或頂層字段。第四步緩存 Schema把生成結果寫回.openapi_schema屬性作為“緩存”避免每次用戶打開 API 文檔時都重新生成一遍app.openapi_schema openapi_schema return app.openapi_schema這樣 Schema 只在首次請求時生成一次后續請求直接復用緩存。前面提到默認實現中.openapi()還帶路由版本比對而這里的自定義實現做了簡化——如果你后續動態注冊了新路由且希望 Schema 自動更新可以在函數里自行加入類似的版本判斷邏輯。第五步替換.openapi()方法最后把應用的方法替換為你的新函數FastAPI 內部的/openapi.json路徑操作與 Swagger UI / ReDoc 都會自動走新實現app.openapi custom_openapi驗證效果運行應用后訪問 http://127.0.0.1:8000/redoc可以看到文檔頁使用了自定義 Logo本例中是 FastAPI 的 Logo而不是默認樣式。源碼與測試層面的印證這套用法在倉庫中有完整的實現與測試支撐get_openapi()的實現位于 fastapi/openapi/utils.py其中對路由的遍歷通過routing.iter_route_contexts(routes)完成逐一調用get_openapi_path()生成每個路徑操作的 OpenAPI 描述并統一收集securitySchemes與模型定義最終排序寫入components.schemas。.openapi()默認實現位于 fastapi/applications.py它把應用構造參數title、version、summary、servers、webhooks、tags、separate_input_output_schemas等一一透傳給get_openapi()這就是為什么替換方法后需要自行把需要的參數重新傳進去。注冊/openapi.json路由位于 fastapi/applications.py 的setup()方法它會以include_in_schemaFalse注冊該路由并在有root_path反向代理前綴時把根路徑寫入servers。測試用例位于 tests/test_tutorial/test_extending_openapi/test_tutorial001.py它通過TestClient斷言/openapi.json返回的 Schema 精確匹配快照——info中包含了自定義的title、summary、description、version以及x-logo同時路徑/items/下的GET操作也被完整收集測試還連續請求兩次/openapi.json驗證了自定義緩存生效兩次返回完全一致。這證明“生成 → 修改 → 緩存 → 替換方法”的整套流程是可運行、可回歸驗證的。常見應用場景與注意事項注入廠商擴展除x-logo外還可按需注入x-codeSamples、x-tagGroups等 ReDoc/Swagger UI 擴展操作方式與上文完全一致。定制文檔元數據動態修改info.description、info.contact、info.license或按部署環境切換servers列表。統一調整操作 ID 或標簽可以在custom_openapi()里對生成后的paths字典做二次遍歷改寫例如規范化operationIdpaths的鍵即為路由路徑模板如/items/值內是各 HTTP 方法的操作對象。緩存與動態路由自定義實現返回.openapi_schema時要注意它不再像默認實現那樣自動比對路由版本若你的應用會在運行期動態添加路由建議在函數內保留類似_openapi_routes_version的比對邏輯。文檔頁面不受影響替換.openapi()方法后/docsSwagger UI與/redoc的 HTML 頁面本身不需要任何改動它們都從同一個 OpenAPI Schema 渲染因此自定義內容會同步出現在兩種文檔中。小結FastAPI 的 OpenAPI 生成鏈路設計得高度可替換默認實現把「生成get_openapi— 緩存.openapi_schema— 輸出/openapi.json」三個環節解耦開發者只需覆蓋.openapi()方法即可完全接管 Schema 的生成與定制。以x-logo為例的完整流程——復用工具函數生成、字典式修改、寫回緩存、替換方法——既簡單又規范兼容是擴展 API 文檔能力的通用模板。相關參考文件示例源碼 docs_src/extending_openapi/tutorial001_py310.py、核心實現 fastapi/openapi/utils.py 與 fastapi/applications.py、測試用例 tests/test_tutorial/test_extending_openapi/test_tutorial001.py。【免費下載鏈接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production項目地址: https://gitcode.com/GitHub_Trending/fa/fastapi創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 FastAPI 擴展 OpenAPI：自定義 /openapi.json 生成流程的完整指南
FastAPI 擴展 OpenAPI自定義 /openapi.json 生成流程的完整指南【免費下載鏈接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production項目地址: https://gitcode.com/GitHub_Trending/fa/fastapi導讀本文圍繞 FastAPI 中如何修改自動生成的 OpenAPI Schema 展開先剖析/openapi.json的默認生成鏈路.openapi()→.openapi_schema緩存 →fastapi.openapi.utils.get_openapi再以“給 ReDoc 文檔注入自定義 Logo”為例演示如何用同一個工具函數重新生成 Schema、按需覆蓋字段并緩存與替換默認方法。讀完本文你將能夠在不改動框架源碼的前提下為任何 FastAPI 應用定制 OpenAPI 輸出例如注入廠商擴展、調整info元數據、控制servers與tags等。默認的 OpenAPI 生成流程The normal process每一個FastAPI應用實例都帶有一個.openapi()方法它負責返回應用的 OpenAPI Schema。默認流程如下在創建應用對象時setup()階段FastAPI 會為/openapi.json或你在openapi_url中配置的其他路徑注冊一個路徑操作path operation見 applications.py。該路徑操作只是把應用.openapi()方法的返回值包裝成JSONResponse返回并在存在反向代理root_path時自動補充servers前綴。默認的.openapi()方法先檢查屬性.openapi_schema是否已有內容有則直接返回沒有則調用fastapi.openapi.utils.get_openapi生成并把結果緩存到.openapi_schema。從源碼看這一緩存并不是無條件的applications.py中.openapi()會比對路由版本self.router._get_routes_version()只有「緩存為空」或「路由版本已變化」時才重新生成applications.py。也就是說即使你注冊了新路由下一次請求/openapi.json時 Schema 也會自動刷新緩存始終與當前路由保持一致。get_openapi()的關鍵參數get_openapi()定義在 utils.py其核心參數如下參數說明默認值titleOpenAPI 標題顯示在文檔中必填versionAPI 版本例如2.5.0必填openapi_version使用的 OpenAPI 規范版本3.1.0最新summaryAPI 的簡短摘要NonedescriptionAPI 描述可包含 Markdown會渲染在文檔中Noneroutes應用路由取自app.routes用于收集已注冊的路徑操作含被 include 的 Router必填webhooksWebhook 路由取自app.webhooks.routesNonetags頂層tags數組NoneserversOpenAPIservers服務器列表Noneterms_of_service服務條款 URL寫入info.termsOfServiceNonecontact聯系人信息寫入info.contactNonelicense_info許可證信息寫入info.licenseNoneseparate_input_output_schemas是否為輸入/輸出模型生成獨立的 SchemaTrueexternal_docs外部文檔鏈接寫入頂層externalDocsNone技術細節tipapp.routes是更低層的路由樹其中可能包含 FastAPI 為被 include 的 Router 內部使用的路由候選route candidates并非只有最終的APIRoute對象。你仍然可以直接把app.routes傳給get_openapi()——FastAPI 會遍歷這棵路由樹收集真正生效的路徑操作。注意notesummary參數需要 OpenAPI 3.1.0 及以上版本并由 FastAPI 0.99.0 及以上版本支持。get_openapi()內部的組裝邏輯utils.py大致為先構建info對象title/version必填summary、description、termsOfService、contact、license按需寫入再遍歷路由收集paths、securitySchemes與組件定義最后把paths、webhooks、tags、externalDocs等組裝成完整字典經jsonable_encoder(OpenAPI(**output))序列化后返回。覆蓋默認值注入 ReDoc 的自定義 Logo 擴展理解了默認流程后就可以用同一個工具函數重新生成 Schema并覆蓋其中任意部分。官方示例以 ReDoc 的x-logo廠商擴展為例為文檔頁注入自定義 Logo。第一步照常編寫 FastAPI 應用先按平時的習慣寫好整個應用例如在 tutorial001_py310.py 中定義一個GET /items/接口from fastapi import FastAPI from fastapi.openapi.utils import get_openapi app FastAPI() app.get(/items/) async def read_items(): return [{name: Foo}]第二步生成 OpenAPI Schema定義一個custom_openapi()函數在其中調用同一個工具函數生成 Schemadef custom_openapi(): if app.openapi_schema: return app.openapi_schema openapi_schema get_openapi( titleCustom title, version2.5.0, summaryThis is a very custom OpenAPI schema, descriptionHeres a longer description of the custom **OpenAPI** schema, routesapp.routes, ) ...注意這里重寫了title、version、summary、description你可以按需傳入前面表格中的任意參數例如servers[{url: https://api.example.com}]或tags[{name: items, description: Item operations}]。第三步修改 OpenAPI Schemaget_openapi()返回的是普通字典直接操作即可。這里在info對象上加入x-logo擴展讓 ReDoc 顯示自定義 Logoopenapi_schema[info][x-logo] { url: https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png }x-logo是 ReDoc 的廠商擴展vendor extensionOpenAPI 規范允許所有x-前綴的字段存在因此這種覆蓋方式是規范兼容的。你同樣可以擴展其他任何info子字段或頂層字段。第四步緩存 Schema把生成結果寫回.openapi_schema屬性作為“緩存”避免每次用戶打開 API 文檔時都重新生成一遍app.openapi_schema openapi_schema return app.openapi_schema這樣 Schema 只在首次請求時生成一次后續請求直接復用緩存。前面提到默認實現中.openapi()還帶路由版本比對而這里的自定義實現做了簡化——如果你后續動態注冊了新路由且希望 Schema 自動更新可以在函數里自行加入類似的版本判斷邏輯。第五步替換.openapi()方法最后把應用的方法替換為你的新函數FastAPI 內部的/openapi.json路徑操作與 Swagger UI / ReDoc 都會自動走新實現app.openapi custom_openapi驗證效果運行應用后訪問 http://127.0.0.1:8000/redoc可以看到文檔頁使用了自定義 Logo本例中是 FastAPI 的 Logo而不是默認樣式。源碼與測試層面的印證這套用法在倉庫中有完整的實現與測試支撐get_openapi()的實現位于 fastapi/openapi/utils.py其中對路由的遍歷通過routing.iter_route_contexts(routes)完成逐一調用get_openapi_path()生成每個路徑操作的 OpenAPI 描述并統一收集securitySchemes與模型定義最終排序寫入components.schemas。.openapi()默認實現位于 fastapi/applications.py它把應用構造參數title、version、summary、servers、webhooks、tags、separate_input_output_schemas等一一透傳給get_openapi()這就是為什么替換方法后需要自行把需要的參數重新傳進去。注冊/openapi.json路由位于 fastapi/applications.py 的setup()方法它會以include_in_schemaFalse注冊該路由并在有root_path反向代理前綴時把根路徑寫入servers。測試用例位于 tests/test_tutorial/test_extending_openapi/test_tutorial001.py它通過TestClient斷言/openapi.json返回的 Schema 精確匹配快照——info中包含了自定義的title、summary、description、version以及x-logo同時路徑/items/下的GET操作也被完整收集測試還連續請求兩次/openapi.json驗證了自定義緩存生效兩次返回完全一致。這證明“生成 → 修改 → 緩存 → 替換方法”的整套流程是可運行、可回歸驗證的。常見應用場景與注意事項注入廠商擴展除x-logo外還可按需注入x-codeSamples、x-tagGroups等 ReDoc/Swagger UI 擴展操作方式與上文完全一致。定制文檔元數據動態修改info.description、info.contact、info.license或按部署環境切換servers列表。統一調整操作 ID 或標簽可以在custom_openapi()里對生成后的paths字典做二次遍歷改寫例如規范化operationIdpaths的鍵即為路由路徑模板如/items/值內是各 HTTP 方法的操作對象。緩存與動態路由自定義實現返回.openapi_schema時要注意它不再像默認實現那樣自動比對路由版本若你的應用會在運行期動態添加路由建議在函數內保留類似_openapi_routes_version的比對邏輯。文檔頁面不受影響替換.openapi()方法后/docsSwagger UI與/redoc的 HTML 頁面本身不需要任何改動它們都從同一個 OpenAPI Schema 渲染因此自定義內容會同步出現在兩種文檔中。小結FastAPI 的 OpenAPI 生成鏈路設計得高度可替換默認實現把「生成get_openapi— 緩存.openapi_schema— 輸出/openapi.json」三個環節解耦開發者只需覆蓋.openapi()方法即可完全接管 Schema 的生成與定制。以x-logo為例的完整流程——復用工具函數生成、字典式修改、寫回緩存、替換方法——既簡單又規范兼容是擴展 API 文檔能力的通用模板。相關參考文件示例源碼 docs_src/extending_openapi/tutorial001_py310.py、核心實現 fastapi/openapi/utils.py 與 fastapi/applications.py、測試用例 tests/test_tutorial/test_extending_openapi/test_tutorial001.py。【免費下載鏈接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production項目地址: https://gitcode.com/GitHub_Trending/fa/fastapi創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考