Comment définir l'interface API à l'aide de la spécification OpenAPI dans FastAPI

Comment définir l'interface API à l'aide de la spécification OpenAPI dans FastAPI

Introduction :
Lors de l'écriture d'une API Web, une bonne documentation de l'API est très importante. Il peut fournir une documentation claire et des définitions d'interface pour aider les développeurs à comprendre et à utiliser rapidement les API. La spécification OpenAPI est un langage de description d'API universel doté de fonctions puissantes et d'un support d'écosystème qui nous permet de définir et de générer des documents API d'une manière basée sur des normes. FastAPI est un framework Web Python moderne qui intègre parfaitement la spécification OpenAPI et fournit de puissantes fonctions automatisées de génération et de vérification de documents. Cet article explique comment utiliser la spécification OpenAPI pour définir des interfaces API dans FastAPI et fournit des exemples de code correspondants.

1. Installer les bibliothèques FastAPI et pydantic
Avant de commencer, nous devons installer les bibliothèques FastAPI et pydantic. Ils peuvent être installés via la commande suivante :

pip install fastapi
pip install uvicorn[standard]
pip install pydantic

2. Créez une interface API simple
Tout d'abord, nous créons une interface API simple pour montrer comment utiliser la spécification OpenAPI. Dans un fichier nommé main.py, écrivez le code suivant : 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}rrreee

Ce code crée une interface de requête GET pour /hello et renvoie une interface de requête GET contenant la réponse JSON pour le champ message. Ensuite, nous devons exécuter l'application. Il peut être exécuté via la commande suivante :

rrreee
3. Générez la documentation OpenAPI

Après avoir exécuté l'application, vous pouvez ouvrir http://localhost:8000/docs dans le navigateur pour accéder au fichier généré automatiquement. Documentation API. Cette page est un document généré automatiquement par FastAPI basé sur la spécification OpenAPI. Vous pouvez voir les détails de l'interface /hello, y compris le chemin, la méthode de requête, les paramètres de requête et des exemples de réponse. De plus, vous pouvez également tester cette interface dans la page de documentation. 🎜🎜4. Utiliser la définition des paramètres🎜Dans les applications réelles, nous devons généralement utiliser des paramètres pour recevoir les entrées de l'utilisateur. FastAPI propose plusieurs façons de définir des paramètres, notamment les paramètres de chemin, les paramètres de requête, les paramètres de corps de requête et les paramètres d'en-tête de requête. Ci-dessous, nous montrerons comment utiliser ces paramètres. 🎜🎜4.1 Paramètres de chemin🎜Les paramètres de chemin font partie de l'URL, ils sont utilisés pour recevoir des variables dynamiques. Nous pouvons définir un paramètre de chemin via {}. Dans l'exemple ci-dessous, nous créons une interface qui accepte un ID utilisateur comme paramètre de chemin. 🎜rrreee🎜En exécutant l'application puis en visitant http://localhost:8000/users/1 dans votre navigateur, vous obtiendrez une réponse JSON {"user_id": 1} code>. 🎜🎜4.2 Paramètres de requête🎜Les paramètres de requête font partie de l'URL et sont utilisés pour recevoir des paires clé-valeur transmises par l'utilisateur. Dans FastAPI, les paramètres de requête peuvent être définis via des valeurs par défaut dans les paramètres de fonction. Dans l'exemple ci-dessous, nous créons une interface qui accepte les paramètres de requête limit et offset. 🎜rrreee🎜En exécutant l'application puis en accédant à http://localhost:8000/users/?limit=20&offset=10 dans votre navigateur, vous obtiendrez une réponse JSON {"limit" : 20, "offset": 10}. 🎜🎜4.3 Paramètres du corps de la requête🎜Les paramètres du corps de la requête sont des données transmises via le corps de la requête HTTP et sont généralement utilisés pour recevoir des données plus volumineuses. Dans FastAPI, les paramètres du corps de la requête peuvent être définis via le modèle de la bibliothèque pydantic. Dans l'exemple suivant, nous créons une interface qui accepte les informations utilisateur comme paramètre de corps de requête. 🎜rrreee🎜Après avoir exécuté l'application, utilisez un outil tel que curl pour envoyer une requête POST : 🎜rrreee🎜Vous obtiendrez une réponse JSON {"user": {"name": " Alice", " âge": 25}}. 🎜🎜4.4 Paramètres d'en-tête de requête🎜Les paramètres d'en-tête de requête sont des paramètres transmis via les en-têtes de requête HTTP et sont généralement utilisés pour transmettre des informations de vérification de sécurité. Dans FastAPI, les paramètres d'en-tête de requête peuvent être définis à l'aide de la méthode Header() dans les paramètres de fonction. Dans l'exemple ci-dessous, nous créons une interface qui accepte le paramètre d'en-tête de requête api_key. 🎜rrreee🎜En exécutant l'application puis en accédant à http://localhost:8000/protected/ dans le navigateur et en portant l'en-tête de requête api_key personnalisé, vous obtiendrez un JSON réponse {"api_key": 9ce267272c0436a4c78c6fffce6a6865}. 🎜🎜Conclusion : 🎜Cet article explique comment utiliser la spécification OpenAPI pour définir les interfaces API dans FastAPI. En utilisant les décorateurs et les annotations de types de paramètres fournis par FastAPI, nous pouvons facilement définir et vérifier les interfaces API. Grâce à la documentation OpenAPI générée automatiquement, nous pouvons rapidement comprendre et utiliser l'interface API, et pouvons facilement collaborer et communiquer avec d'autres développeurs. J'espère que cet article pourra vous aider à mieux définir et utiliser les interfaces API dans FastAPI. 🎜

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!