Định nghĩa OpenAPI Schema with FastAPI

OpenAPI là một đặc tả mô tả các API RESTful bằng một định dạng tiêu chuẩn. Nó cho phép các nhà phát triển định nghĩa cấu trúc, các điểm cuối (endpoints), tham số và phản hồi của một API.

FastAPI, một framework web hiện đại cho việc xây dựng các API với Python, cung cấp hỗ trợ tích hợp sẵn cho việc tạo ra các schema OpenAPI.

Trong bài viết này, chúng tôi sẽ hướng dẫn bạn qua quá trình định nghĩa một schema OpenAPI bằng FastAPI.

OpenAPI là gì?

OpenAPI, trước đây được biết đến với tên gọi là Swagger, là một đặc tả cung cấp một định dạng có thể đọc được bằng máy tính để mô tả và tài liệu hóa các API RESTful. Nó sử dụng định dạng JSON hoặc YAML để định nghĩa các điểm cuối (endpoints), phương thức, tham số, các phần thân yêu cầu/phản hồi và các chi tiết khác của một API.

OpenAPI cho phép các nhà phát triển thiết kế và tài liệu hóa các API một cách nhất quán và tiêu chuẩn, giúp việc hiểu và tương tác với API trở nên dễ dàng hơn đối với các khách hàng.

FastAPI và OpenAPI

FastAPI đơn giản hóa quá trình định nghĩa một schema OpenAPI bằng cách tự động tạo ra nó dựa trên mã code API của bạn. FastAPI tận dụng sức mạnh của các mô hình Pydantic và các chú thích kiểu dữ liệu để tạo ra một schema OpenAPI chính xác và chi tiết. Bằng cách sử dụng FastAPI, bạn có thể tập trung vào việc xây dựng chức năng của API của mình trong khi để nó xử lý việc tạo ra schema OpenAPI cho bạn.

Định nghĩa một schema OpenAPI bằng FastAPI

Import Dependencies:

Bắt đầu bằng cách import dependencies cần thiết vào trong tập tin Python của bạn (main.py):

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

Tạo FastAPI App:

Tạo FastAPI application instance

app = FastAPI()

Định nghĩa API Routes:

@app.get("/users/{user_id}")
def get_user(user_id: int):
    """
    Retrieve user information by ID.
    """
    # ...
    return {"user_id": user_id, "name": "Quang Le"}

Generate OpenAPI Schema:

def generate_openapi_schema():
    """
    Generate the OpenAPI schema for the FastAPI application.
    """
    return get_openapi(
        title="My API",
        version="1.0.0",
        description="This is my API description",
        routes=app.routes,
    )

Expose OpenAPI Endpoint:

@app.get("/openapi.json")
def get_openapi_endpoint():
    """
    Retrieve the generated OpenAPI schema.
    """
    return JSONResponse(content=generate_openapi_schema())

Đảm bảo nhập JSONResponse từ fastapi.responses ở đầu tập tin của bạn.

Run the App:

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
from fastapi.responses import JSONResponse
import uvicorn

app = FastAPI()

def generate_openapi_schema():
    """
    Generate the OpenAPI schema for the FastAPI application.
    """
    return get_openapi(
        title="My API",
        version="1.0.0",
        description="This is my API description",
        routes=app.routes,
    )

@app.get("/users/{user_id}")
def get_user(user_id: int):
    """
    Retrieve user information by ID.
    """
    # ...
    return {"user_id": user_id, "name": "John Doe"}

@app.get("/openapi.json")
def get_openapi_endpoint():
    """
    Retrieve the generated OpenAPI schema.
    """
    return JSONResponse(content=generate_openapi_schema())

if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=8200)

Cuối cùng, chạy ứng dụng FastAPI của bạn bằng Uvicorn hoặc bất kỳ ASGI server nào khác mà bạn chọn:

python main.py
or
uvicorn main:app --host 127.0.0.1 --port 8200

Testing the OpenAPI Schema

Để kiểm tra schema OpenAPI được tạo ra, khởi chạy ứng dụng FastAPI và truy cập vào điểm cuối /openapi.json trong trình duyệt của bạn. Bạn sẽ thấy schema OpenAPI được tạo ra trong định dạng JSON, mô tả các điểm cuối API, tham số và phản hồi.

Xem thêm bài viết của mình tại đây