Bagaimana untuk menentukan antara muka API menggunakan spesifikasi OpenAPI dalam FastAPI

Cara menentukan antara muka API menggunakan spesifikasi OpenAPI dalam FastAPI

Pengenalan:
Apabila menulis API Web, dokumentasi API yang baik adalah sangat penting. Ia boleh memberikan dokumentasi yang jelas dan definisi antara muka untuk membantu pembangun memahami dan menggunakan API dengan cepat. Spesifikasi OpenAPI ialah bahasa penerangan API umum dengan fungsi berkuasa dan sokongan ekosistem yang membolehkan kami mentakrif dan menjana dokumen API dalam cara berasaskan piawai. FastAPI ialah rangka kerja web Python moden yang menyepadukan dengan sempurna spesifikasi OpenAPI dan menyediakan penjanaan dokumen automatik yang berkuasa dan fungsi pengesahan. Artikel ini akan memperkenalkan cara menggunakan spesifikasi OpenAPI untuk menentukan antara muka API dalam FastAPI dan menyediakan contoh kod yang sepadan.

1. Pasang FastAPI dan perpustakaan pydantic
Sebelum bermula, kita perlu memasang perpustakaan FastAPI dan pydantic. Ia boleh dipasang melalui arahan berikut:

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

2. Cipta antara muka API yang mudah
Pertama, kami mencipta antara muka API yang mudah untuk menunjukkan cara menggunakan spesifikasi OpenAPI. Dalam fail bernama main.py, tulis kod berikut: 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>}rrreee

Kod ini mencipta antara muka permintaan GET untuk /hello dan mengembalikan antara muka permintaan GET yang mengandungi respons JSON untuk medan mesej. Seterusnya, kita perlu menjalankan aplikasi. Ia boleh dijalankan melalui arahan berikut:

rrreee
3. Jana dokumentasi OpenAPI

Selepas menjalankan aplikasi, anda boleh membuka http://localhost:8000/docs dalam penyemak imbas untuk mengakses yang dijana secara automatik dokumentasi API. Halaman ini ialah dokumen yang dijana secara automatik oleh FastAPI berdasarkan spesifikasi OpenAPI. Anda boleh melihat butiran antara muka /hello, termasuk laluan, kaedah permintaan, parameter permintaan dan contoh respons. Selain itu, anda juga boleh menguji antara muka ini dalam halaman dokumentasi. 🎜🎜4. Gunakan definisi parameter🎜Dalam aplikasi sebenar, kita biasanya perlu menggunakan parameter untuk menerima input pengguna. FastAPI menyediakan pelbagai cara untuk menentukan parameter, termasuk parameter laluan, parameter pertanyaan, parameter badan permintaan dan parameter pengepala permintaan. Di bawah ini kami akan menunjukkan cara menggunakan parameter ini. 🎜🎜4.1 Parameter laluan 🎜Parameter laluan adalah sebahagian daripada URL, ia digunakan untuk menerima pembolehubah dinamik. Kita boleh mentakrifkan parameter laluan melalui {}. Dalam contoh di bawah, kami mencipta antara muka yang menerima ID pengguna sebagai parameter laluan. 🎜rrreee🎜Dengan menjalankan apl dan kemudian melawati http://localhost:8000/users/1 dalam penyemak imbas anda, anda akan mendapat respons JSON {"user_id": 1} kod>. 🎜🎜4.2 Parameter pertanyaan🎜Parameter pertanyaan ialah sebahagian daripada URL dan digunakan untuk menerima pasangan nilai kunci yang diluluskan oleh pengguna. Dalam FastAPI, parameter pertanyaan boleh ditakrifkan melalui nilai lalai dalam parameter fungsi. Dalam contoh di bawah, kami mencipta antara muka yang menerima parameter pertanyaan had dan offset. 🎜rrreee🎜Dengan menjalankan apl dan kemudian mengakses http://localhost:8000/users/?limit=20&offset=10 dalam penyemak imbas anda, anda akan mendapat respons JSON {"limit" : 20, "offset": 10}. 🎜🎜4.3 Parameter badan permintaan🎜Parameter badan permintaan ialah data yang dihantar melalui badan permintaan HTTP dan biasanya digunakan untuk menerima data yang lebih besar. Dalam FastAPI, parameter badan permintaan boleh ditakrifkan melalui model pustaka pydantic. Dalam contoh berikut, kami mencipta antara muka yang menerima maklumat pengguna sebagai parameter badan permintaan. 🎜rrreee🎜Selepas menjalankan aplikasi, gunakan alat seperti curl untuk menghantar permintaan POST: 🎜rrreee🎜Anda akan mendapat respons JSON {"user": {"name": " Alice", " umur": 25}}. 🎜🎜4.4 Parameter pengepala permintaan🎜Parameter pengepala permintaan ialah parameter yang dihantar melalui pengepala permintaan HTTP dan biasanya digunakan untuk menghantar maklumat pengesahan keselamatan. Dalam FastAPI, parameter pengepala permintaan boleh ditakrifkan menggunakan kaedah Header() dalam parameter fungsi. Dalam contoh di bawah, kami mencipta antara muka yang menerima parameter pengepala permintaan api_key. 🎜rrreee🎜Dengan menjalankan aplikasi dan kemudian mengakses http://localhost:8000/protected/ dalam penyemak imbas dan membawa pengepala permintaan api_key tersuai, anda akan mendapat JSON respons {"api_key": <your_api_key>}. 🎜🎜Kesimpulan: 🎜Artikel ini memperkenalkan cara menggunakan spesifikasi OpenAPI untuk menentukan antara muka API dalam FastAPI. Dengan menggunakan penghias dan anotasi jenis parameter yang disediakan oleh FastAPI, kami boleh mentakrif dan mengesahkan antara muka API dengan mudah. Melalui dokumentasi OpenAPI yang dijana secara automatik, kami boleh memahami dan menggunakan antara muka API dengan cepat, serta boleh bekerjasama dan berkomunikasi dengan mudah dengan pembangun lain. Saya harap artikel ini dapat membantu anda mentakrifkan dan menggunakan antara muka API dengan lebih baik dalam FastAPI. 🎜

Atas ialah kandungan terperinci Bagaimana untuk menentukan antara muka API menggunakan spesifikasi OpenAPI dalam FastAPI. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!