FastAPI 中的 OpenAPI Callbacks用callbacks參數(shù)自動(dòng)文檔化外部回調(diào) API【免費(fèi)下載鏈接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production項(xiàng)目地址: https://gitcode.com/GitHub_Trending/fa/fastapi本文圍繞 FastAPI 官方教程docs/de/docs/advanced/openapi-callbacks.mdOpenAPI-Callbacks展開當(dāng)你的 API 在處理請(qǐng)求后會(huì)反過來調(diào)用外部開發(fā)者的 API即回調(diào)時(shí)如何用一個(gè)APIRouter加上路徑操作裝飾器的callbacks參數(shù)把這條回調(diào)契約完整寫入 OpenAPI 規(guī)范并自動(dòng)展示在 Swagger UI 的 Callbacks 標(biāo)簽頁中。讀完后你將能夠定義帶回調(diào)文檔的 FastAPI 應(yīng)用、使用 OpenAPI 3 表達(dá)式讓回調(diào)路徑動(dòng)態(tài)引用原始請(qǐng)求中的參數(shù)與 Body 字段并在/docs中驗(yàn)證外部開發(fā)者應(yīng)實(shí)現(xiàn)的接口形態(tài)。什么是 OpenAPI Callbacks先理解回調(diào)場(chǎng)景你可以構(gòu)建一種 API其中某個(gè)路徑操作path operation在處理過程中會(huì)觸發(fā)對(duì)外部 API的請(qǐng)求——這個(gè)外部 API 由別人創(chuàng)建通常正是那個(gè)正在使用你 API 的開發(fā)者。這個(gè)過程被稱為Callback回調(diào)外部開發(fā)者編寫的軟件先向你的 API 發(fā)送請(qǐng)求隨后你的 API 再回?fù)躢alls back向該外部 API 發(fā)送一個(gè)請(qǐng)求。此時(shí)你往往希望文檔化這條外部 API 應(yīng)有的樣子它應(yīng)包含哪個(gè)路徑操作哪個(gè)方法、哪個(gè)路徑它應(yīng)接收什么樣的請(qǐng)求 Body它應(yīng)返回什么樣的響應(yīng)。FastAPI 借助 OpenAPI 規(guī)范原生的callbacks字段讓你復(fù)用寫 FastAPI 路徑操作的全部經(jīng)驗(yàn)來描述這條外部 API——包括參數(shù)聲明、Pydantic 請(qǐng)求體模型和response_model。示例場(chǎng)景一個(gè)帶回調(diào)的發(fā)票應(yīng)用用一個(gè)具體例子貫穿全文假設(shè)你開發(fā)了一個(gè)發(fā)票創(chuàng)建應(yīng)用。每張發(fā)票包含id、title可選、customer、total。你的 API 使用者一個(gè)外部開發(fā)者通過 POST 請(qǐng)求在你的 API 中創(chuàng)建一張發(fā)票。隨后你的 API假設(shè)性地會(huì)把發(fā)票發(fā)送給該外部開發(fā)者的某個(gè)客戶收齊款項(xiàng)向 API 使用者外部開發(fā)者發(fā)回一條通知——這一步是通過你的 API 向外部開發(fā)者提供的外部 API 發(fā)送一個(gè) POST 請(qǐng)求實(shí)現(xiàn)的這就是回調(diào)。下面的教程代碼位于 docs_src/openapi_callbacks/tutorial001_py310.py完整文件僅 51 行本文會(huì)逐段講解。普通的 FastAPI 應(yīng)用部分先看在加入回調(diào)之前常規(guī) API 應(yīng)用長(zhǎng)什么樣。它有一個(gè)路徑操作接收Invoice請(qǐng)求體并帶一個(gè)攜帶回調(diào) URL 的查詢參數(shù)callback_urlfrom fastapi import APIRouter, FastAPI from pydantic import BaseModel, HttpUrl app FastAPI() class Invoice(BaseModel): id: str title: str | None None customer: str total: floatapp.post(/invoices/, callbacksinvoices_callback_router.routes) def create_invoice(invoice: Invoice, callback_url: HttpUrl | None None): Create an invoice. ... # Send the invoice, collect the money, send the notification (the callback) return {msg: Invoice received}這里有一個(gè)值得注意的細(xì)節(jié)callback_url查詢參數(shù)使用了 Pydantic 的HttpUrl類型見 docs_src/openapi_callbacks/tutorial001_py310.py。從生成的 OpenAPI 測(cè)試快照可以看到該參數(shù)被渲染為format: uri、minLength: 1、maxLength: 2083的字符串 schema且因HttpUrl | None而變?yōu)榭蛇xrequired: False見 tests/test_sub_callbacks.py。上面代碼中唯一新的東西是傳給路徑操作裝飾器的參數(shù)callbacksinvoices_callback_router.routes下面詳解。文檔化回調(diào)本身真正的回調(diào)代碼有多簡(jiǎn)單實(shí)際的回調(diào)實(shí)現(xiàn)代碼強(qiáng)烈依賴于你自己的業(yè)務(wù)因應(yīng)用而異可能只是短短一兩行例如callback_url https://example.com/api/v1/invoices/events/ httpx.post(callback_url, json{description: Invoice paid, paid: True})但回調(diào)中最關(guān)鍵的部分是確保你的 API 使用者外部開發(fā)者正確實(shí)現(xiàn)了那條外部 API——按照你的 API 將在回調(diào)請(qǐng)求體中發(fā)送的數(shù)據(jù)格式來實(shí)現(xiàn)。本教程示例不實(shí)現(xiàn)回調(diào)本身它可能只有一行代碼只演示文檔化的部分。提示實(shí)際的回調(diào)本質(zhì)上就是一個(gè) HTTP 請(qǐng)求。實(shí)現(xiàn)時(shí)可以使用httpx、requests等任意 HTTP 客戶端庫。這一點(diǎn)也被 FastAPI 源碼的官方文檔字符串明確確認(rèn)callbacks參數(shù)的 Doc 寫著 List ofpath operationsthat will be used as OpenAPI callbacks.This is only for OpenAPI documentation, the callbacks wont be used directly.It will be added to the generated OpenAPI (e.g. visible at/docs)見 fastapi/applications.py 中include_router的callbacks參數(shù)說明。也就是說回調(diào)路由永遠(yuǎn)不會(huì)被你的應(yīng)用執(zhí)行它們只用于生成 OpenAPI 文檔。編寫回調(diào)文檔代碼把自己想象成外部開發(fā)者用來文檔化回調(diào)的代碼不會(huì)在你的應(yīng)用中執(zhí)行你只是需要它來描述那條外部 API 應(yīng)長(zhǎng)什么樣。但你已經(jīng)知道如何用 FastAPI 輕松創(chuàng)建自動(dòng)文檔——于是用同樣的方法把外部 API 應(yīng)實(shí)現(xiàn)的路徑操作寫出來即可。提示編寫回調(diào)文檔代碼時(shí)不妨想象自己就是那個(gè)外部開發(fā)者此刻正在實(shí)現(xiàn)的不是你的 API而是外部 API。暫時(shí)切換到這個(gè)視角后參數(shù)放在哪里、Body 用哪個(gè) Pydantic 模型、Response 是什么都會(huì)變得直觀。第 1 步創(chuàng)建一個(gè)回調(diào)APIRouter先新建一個(gè)APIRouter用來裝一個(gè)或多個(gè)回調(diào)from fastapi import APIRouter, FastAPI invoices_callback_router APIRouter()見 docs_src/openapi_callbacks/tutorial001_py310.py。第 2 步創(chuàng)建回調(diào)路徑操作使用上面創(chuàng)建的APIRouter來定義回調(diào)路徑操作它看起來就像一條普通的 FastAPI路徑操作聲明它應(yīng)接收的 Body如body: InvoiceEvent可以聲明它應(yīng)返回的響應(yīng)如response_modelInvoiceEventReceivedclass InvoiceEvent(BaseModel): description: str paid: bool class InvoiceEventReceived(BaseModel): ok: bool invoices_callback_router APIRouter() invoices_callback_router.post( {$callback_url}/invoices/{$request.body.id}, response_modelInvoiceEventReceived ) def invoice_notification(body: InvoiceEvent): pass見 docs_src/openapi_callbacks/tutorial001_py310.py。與普通路徑操作相比有兩個(gè)主要區(qū)別函數(shù)體不需要真實(shí)代碼因?yàn)槟愕膽?yīng)用永遠(yuǎn)不會(huì)調(diào)用它它只用于文檔化外部 API所以函數(shù)體可以只有pass。路徑可以包含 OpenAPI 3 表達(dá)式可以引用發(fā)送到你 API 的原始請(qǐng)求中的變量參數(shù)和請(qǐng)求體部分。回調(diào)路徑表達(dá)式OpenAPI 3 expression回調(diào)路徑可以是一個(gè)OpenAPI 3 表達(dá)式str字符串其中可以內(nèi)嵌對(duì)原始請(qǐng)求內(nèi)容的引用。本例中是{$callback_url}/invoices/{$request.body.id}表達(dá)式的語義{$callback_url}取自原始請(qǐng)求的查詢參數(shù)callback_url{$request.body.id}取自原始請(qǐng)求 JSON Body 中的id字段。完整走一遍數(shù)據(jù)流外部開發(fā)者向你的 API發(fā)送請(qǐng)求https://yourapi.com/invoices/?callback_urlhttps://www.external.org/eventsJSON Body 為{ id: 2expen51ve, customer: Mr. Richie Rich, total: 9999 }你的 API 處理完發(fā)票后在某個(gè)時(shí)刻會(huì)向callback_url即外部 API發(fā)送回調(diào)請(qǐng)求https://www.external.org/events/invoices/2expen51ve回調(diào)的 JSON Body 大致為{ description: Payment celebration, paid: true }并期望從該外部 API收到如下 JSON 響應(yīng){ ok: true }注意最終使用的回調(diào) URL 同時(shí)包含了兩處信息——作為查詢參數(shù)傳入的callback_urlhttps://www.external.org/events和 JSON Body 中的發(fā)票id2expen51ve。這正是 OpenAPI 表達(dá)式相對(duì)靜態(tài)路徑的價(jià)值所在。第 3 步把回調(diào) Router 掛到裝飾器上此時(shí)所需的回調(diào)路徑操作即外部開發(fā)者應(yīng)在外部 API中實(shí)現(xiàn)的接口已經(jīng)放在回調(diào) Router 里?，F(xiàn)在在你的API 的路徑操作裝飾器上通過callbacks參數(shù)傳入該回調(diào) Router 的.routes屬性app.post(/invoices/, callbacksinvoices_callback_router.routes) def create_invoice(invoice: Invoice, callback_url: HttpUrl | None None): ...見 docs_src/openapi_callbacks/tutorial001_py310.py。提示傳給callbacks的不是 Router 本身invoices_callback_router而是它的.routes屬性即invoices_callback_router.routes。FastAPI 會(huì)用這些路由來生成回調(diào)的 OpenAPI 文檔。從源碼看callbacks的類型就是list[BaseRoute] | None在路由初始化時(shí)被原樣存儲(chǔ)到路由對(duì)象上見 fastapi/routing.py 中_populate_api_route_state的callbacks參數(shù)與 fastapi/routing.py 的route.callbacks callbacks。回調(diào)如何被寫入 OpenAPI源碼視角OpenAPI 生成時(shí)FastAPI 遍歷route.callbacks對(duì)每條APIRoute遞歸生成完整的 operation并以回調(diào)函數(shù)名為鍵組織成callbacks字典掛到對(duì)應(yīng) operation 下if route.callbacks: callbacks {} for callback in route.callbacks: if isinstance(callback, routing.APIRoute): ( cb_path, cb_security_schemes, cb_definitions, ) get_openapi_path(route..., ...) callbacks[callback.name] {callback.path: cb_path} operation[callbacks] callbacks見 fastapi/openapi/utils.py。這解釋了兩件事回調(diào) operation 會(huì)像普通操作一樣生成operationId、requestBody、responses且回調(diào)中引用的 Pydantic 模型InvoiceEvent、InvoiceEventReceived也會(huì)進(jìn)入components/schemas該處同時(shí)收集回調(diào)路由的模型定義見 fastapi/openapi/utils.py 的get_fields_from_routes(api_route.callbacks)回調(diào)的鍵是回調(diào)函數(shù)的name如invoice_notification值是以表達(dá)式路徑字符串{$callback_url}/invoices/{$request.body.id}注意不是編譯后的正則而是你寫的原始字符串為鍵的 PathItem。測(cè)試快照完整印證了這段實(shí)現(xiàn)在 tests/test_sub_callbacks.py 中/invoices/的 POST operation 下生成了callbacks對(duì)象包含event_callbackGET表達(dá)式{$callback_url}/events/{$request.body.title}與invoice_notificationPOST表達(dá)式{$callback_url}/invoices/{$request.body.id}兩個(gè)回調(diào)且requestBody分別引用#/components/schemas/Event與#/components/schemas/InvoiceEvent。進(jìn)階include_router也可以附加回調(diào)除了逐條掛在路徑操作裝飾器上app.include_router(...)和APIRouter本身也接受callbacks參數(shù)可為 Router 內(nèi)的所有路徑操作附加回調(diào)文檔源碼 Doc 說明為 OpenAPI callbacks that should apply to allpath operationsin this router見 fastapi/routing.py 中APIRouter.include_router的參數(shù)定義。上文的 tests/test_sub_callbacks.py 正是這個(gè)用法POST /invoices/自帶callbacksinvoices_callback_router.routes而app.include_router(subrouter, callbacksevents_callback_router.routes)又追加了一個(gè)event_callback——兩個(gè)來源的回調(diào)最終合并出現(xiàn)在同一 operation 的callbacks中。從源碼結(jié)構(gòu)看_RouterIncludeContext在 include 鏈路上會(huì)持續(xù)合并父級(jí)與子級(jí)的 callbacks見 fastapi/routing.py 的callbacks: list[BaseRoute]字段及 fastapi/routing.py 的合并邏輯。在/docs中驗(yàn)證啟動(dòng)應(yīng)用并訪問http://127.0.0.1:8000/docs你會(huì)看到 Swagger UI 中該路徑操作多出一個(gè)Callbacks標(biāo)簽頁展示外部 API應(yīng)有的樣子從截圖中可以看到Callbacks 區(qū)塊以回調(diào)函數(shù)名invoice_notification為標(biāo)題方法為POST路徑顯示為表達(dá)式原文{$callback_url}/invoices/{$request.body.id}Request body標(biāo)記為 required內(nèi)容為InvoiceEvent的示例值description: string、paid: trueResponses列出 200 等狀態(tài)碼。這正是給外部開發(fā)者看的契約照著這個(gè)結(jié)構(gòu)實(shí)現(xiàn)一個(gè)接收InvoiceEvent并返回InvoiceEventReceived的接口即可正確接收你的回調(diào)。小結(jié)關(guān)鍵要點(diǎn)回顧要點(diǎn)說明依據(jù)callbacks參數(shù)傳入list[BaseRoute]通常為某callback_router.routes而非 Router 本身fastapi/routing.py、docs_src/openapi_callbacks/tutorial001_py310.py回調(diào)只為文檔回調(diào)路徑操作不會(huì)被應(yīng)用執(zhí)行僅用于生成 OpenAPI 文檔函數(shù)體可passfastapi/applications.py表達(dá)式路徑回調(diào)路徑可用{$參數(shù)名}與{$request.body.字段}引用原始請(qǐng)求fastapi/openapi/utils.py、tests/test_sub_callbacks.py掛接位置路徑操作裝飾器app.post(..., callbacks...)與include_router(..., callbacks...)均可fastapi/routing.pycallback_url類型用 PydanticHttpUrl聲明查詢參數(shù)OpenAPI 中渲染為format: uri且可選tests/test_sub_callbacks.py驗(yàn)證方式訪問/docs查看 Callbacks 標(biāo)簽頁或?qū)Ρ?openapi.json中 operation 的callbacks字段tests/test_sub_callbacks.py參考文件教程文檔 docs/de/docs/advanced/openapi-callbacks.md、示例代碼 docs_src/openapi_callbacks/tutorial001_py310.py、核心實(shí)現(xiàn) fastapi/openapi/utils.py 與 fastapi/routing.py、測(cè)試 tests/test_sub_callbacks.py?！久赓M(fèi)下載鏈接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production項(xiàng)目地址: https://gitcode.com/GitHub_Trending/fa/fastapi創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考