如何在FastAPI中使用OpenAPI規格定義API介面
引言:
在撰寫Web API時,良好的API文件是非常重要的。它可以提供清晰的文件和介面定義,幫助開發者快速理解和使用API。 OpenAPI規範是一種通用的API描述語言,它具有強大的功能和生態系統支持,讓我們能夠基於標準的方式定義和產生API文件。 FastAPI是一款現代化的Python Web框架,它完美地整合了OpenAPI規範,提供了強大的自動化文件產生和驗證功能。本文將介紹如何在FastAPI中使用OpenAPI規範定義API接口,並提供對應的程式碼範例。
一、安裝FastAPI和pydantic函式庫
在開始之前,我們需要安裝FastAPI和pydantic函式庫。可以透過以下命令來安裝它們:
pip install fastapi pip install uvicorn[standard] pip install pydantic
二、建立一個簡單的API介面
首先,我們建立一個簡單的API介面來示範如何使用OpenAPI規格。在一個名為main.py
的檔案中,寫入以下程式碼:
from fastapi import FastAPI app = FastAPI() @app.get("/hello") def hello(): return {"message": "Hello, World!"}
這段程式碼創建了一個/hello
的GET請求接口,並返回一個包含message
欄位的JSON回應。接下來,我們需要運行這個應用程式。可以透過以下命令來運行:
uvicorn main:app --reload
三、產生OpenAPI文件
運行應用程式後,可以在瀏覽器中開啟http://localhost:8000/docs
來存取自動產生的API文件。這個頁面是由FastAPI自動產生基於OpenAPI規範的文件。你可以看到/hello
介面的詳細信息,包括路徑、請求方法、請求參數和回應範例。並且,你也可以在文件頁面中測試這個介面。
四、使用參數定義
在現實的應用中,我們通常需要使用參數來接收使用者的輸入。 FastAPI提供了多種方式來定義參數,包括路徑參數、查詢參數、請求體參數和請求頭參數。下面我們將示範如何使用這些參數。
4.1 路徑參數
路徑參數是URL中的一部分,它們用來接收動態變數。我們可以透過{}
來定義一個路徑參數。在下面的範例中,我們建立了一個接受使用者ID作為路徑參數的介面。
from fastapi import FastAPI app = FastAPI() @app.get("/users/{user_id}") def get_user(user_id: int): return {"user_id": user_id}
透過執行應用,然後在瀏覽器中存取http://localhost:8000/users/1
,你將得到一個JSON回應{"user_id": 1 }
。
4.2 查詢參數
查詢參數是URL中的一部分,用來接收使用者傳遞的鍵值對。在FastAPI中,查詢參數可以透過函數參數中的預設值來定義。在下面的範例中,我們建立了一個接受limit
和offset
查詢參數的介面。
from fastapi import FastAPI app = FastAPI() @app.get("/users/") def get_users(limit: int = 10, offset: int = 0): return {"limit": limit, "offset": offset}
透過執行應用,然後在瀏覽器中存取http://localhost:8000/users/?limit=20&offset=10
,你將得到一個JSON回應{ "limit": 20, "offset": 10}
。
4.3 請求體參數
請求體參數是透過HTTP請求體傳遞的數據,通常用於接收較大的數據。在FastAPI中,請求體參數可以透過pydantic
函式庫的模型來定義。在下面的範例中,我們建立了一個接受使用者資訊作為請求體參數的介面。
from fastapi import FastAPI from pydantic import BaseModel app = FastAPI() class User(BaseModel): name: str age: int @app.post("/users/") def create_user(user: User): return {"user": user}
執行應用程式後,使用工具如curl
發送一個POST請求:
curl -X POST -H "Content-Type: application/json" -d '{"name":"Alice", "age": 25}' http://localhost:8000/users/
你將得到一個JSON回應{"user": {"name ": "Alice", "age": 25}}
。
4.4 請求頭參數
請求頭參數是透過HTTP請求頭傳遞的參數,通常用於傳遞安全性驗證訊息。在FastAPI中,請求頭參數可以在函數參數中使用Header()
方法來定義。在下面的範例中,我們建立了一個接受api_key
請求頭參數的介面。
from fastapi import FastAPI, Header app = FastAPI() @app.get("/protected/") def protected(api_key: str = Header(...)): return {"api_key": api_key}
透過執行應用,然後在瀏覽器中存取http://localhost:8000/protected/
並攜帶自訂的api_key
請求頭,你將得到一個JSON回應{"api_key": ca574589290ec34dada9d6aea704ff33}
。
結論:
本文介紹如何在FastAPI中使用OpenAPI規範定義API介面。透過使用FastAPI提供的裝飾器和參數類型註解,我們可以輕鬆定義和驗證API介面。透過自動產生的OpenAPI文檔,我們能夠快速理解和使用API接口,並且可以輕鬆地與其他開發者進行協作和交流。希望這篇文章能幫助你更好地在FastAPI中定義和使用API介面。
以上是如何在FastAPI中使用OpenAPI規範定義API介面的詳細內容。更多資訊請關注PHP中文網其他相關文章!