如何在FastAPI中使用OpenAPI規範定義API介面

如何在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": <your_api_key>}</your_api_key>。

結論：
本文介紹如何在FastAPI中使用OpenAPI規範定義API介面。透過使用FastAPI提供的裝飾器和參數類型註解，我們可以輕鬆定義和驗證API介面。透過自動產生的OpenAPI文檔，我們能夠快速理解和使用API​​接口，並且可以輕鬆地與其他開發者進行協作和交流。希望這篇文章能幫助你更好地在FastAPI中定義和使用API​​介面。

以上是如何在FastAPI中使用OpenAPI規範定義API介面的詳細內容。更多資訊請關注PHP中文網其他相關文章！