ChatGPT先生と挑むFastAPI #3｜POST APIとPydantic

STEP 3では、POST APIを作成し、JSON形式のリクエストボディを受け取る方法を学びます。

Pydanticを使ってリクエストデータの型や必須項目を定義し、FastAPIがどのように入力値を検証するのか確認します。

さらに、Fieldを使った値の制約も追加し、APIに不正なデータが送られた場合の動作について理解します。

今回学ぶこと

今回のステップで学ぶ内容を一覧で出してもらいました。

1. POST API・リクエストボディ・Pydanticの役割を理解する
2. Pydanticモデルを定義する
3. POST APIを作成してJSONを受け取る
4. Swagger UIからPOSTリクエストを送信して確認する
5. 必須項目・型チェックなどPydanticのバリデーションを確認する
6. Fieldを使った入力値の制約を追加する
7. 自力課題

学習開始

それでは学習をはじめます。

POST API・リクエストボディ・Pydanticの役割を理解する

{
  "name": "Keyboard",
  "price": 5000,
  "description": "Mechanical keyboard"
}

FastAPI公式ドキュメントでも、クライアントからAPIへデータを送る場合はリクエストボディを使い、その宣言にはPydanticモデルを利用する方法が基本として説明されています。

FastAPIはその定義を見て、概念的には次のような処理を行います。

さらに、このモデル情報からJSON SchemaやOpenAPIの情報も生成されるため、Swagger UIにもリクエスト形式が自動的に反映されます。

Pydanticモデルを定義する

from fastapi import FastAPI
from pydantic import BaseModel


# 商品登録時に受け取るデータの構造を定義する
class ProductCreate(BaseModel):
    name: str
    price: int
    description: str | None = None


app = FastAPI()

ProductCreate はPydanticの BaseModel を継承して作ります。

そして、以下によって受け取るデータの構造を定義しています。

name: str
price: int
description: str | None = None

ここで重要なのが必須・任意の違いです。
以下はデフォルト値がないため必須です。

name: str
price: int

一方、以下はデフォルト値として None が設定されているため、省略可能です。

description: str | None = None

今後CRUDを作っていくと、以下のように用途ごとにモデルを分けることがあります。

ProductCreate
ProductUpdate
ProductResponse

POST APIを作成してJSONを受け取る

@app.post("/products")
def create_product(product: ProductCreate):
    # リクエストボディから受け取った商品データをそのまま返す
    return product

つまり、クライアントから

{
  "name": "Keyboard",
  "price": 5000,
  "description": "Mechanical keyboard"
}

が送られると、概念的には次のよう流れになります。

そして関数内の product は単なるJSON文字列や辞書ではなく、ProductCreate のインスタンスになっています。

たとえば内部では、次のように値へアクセスできます。

product.name
product.price
product.description

Swagger UIからPOSTリクエストを送信する

実行結果↓

必須項目・型チェックなどPydanticのバリデーションを確認する

実行結果↓

リクエストボディに必須であるpriceがないため、エラーになります。
今回の流れは以下のようになります。

リクエストボディ↓

{
  "name": "Keyboard",
  "price": "abc",
  "description": "Mechanical keyboard"
}

実行結果↓

今回も以下にような流れでエラーが返ってきます。

リクエストボディ↓

{
  "name": "Keyboard",
  "price": 5000
}

実行結果↓

descriptionは、description: str | None = Noneのようにデフォルト値を設定しているため、省略してもエラーになりません。

省略された場合は None が入ります。そしてJSONに変換してレスポンスすると、Pythonの None はJSONの null になります。

Fieldを使った入力値の制約を追加する

まずimportを変更します。

from pydantic import BaseModel, Field

そして price を次のように変更します。

class ProductCreate(BaseModel):
    name: str
    price: int = Field(gt=0)
    description: str | None = None

gt は greater than（より大きい） の意味です。つまり、price > 0という制約になります。

そのため、次のようになります。

price = 5000  # OK
price = 1  # OK
price = 0  # NG
price = -100  # NG

ここで大事なのは、int と Field の役割の違いです。

price: int = Field(gt=0)

この場合、以下のような役割分担になっています。

実行結果↓

自力課題

課題内容

エンドポイント：POST /users

リクエストボディ次の3項目です。

項目	型	条件
name	str	必須
age	int	必須、0より大きい
email	str	任意、省略時はNone

※今回はメールアドレスの形式チェックまでは行いません。str として受け取れればOKです。

POST APIでは、受け取ったPydanticモデルをそのままレスポンスとして返すようにしてください。

完了条件

実装結果

実装したコード（実装箇所のみ抜粋）↓

class UserCreate(BaseModel):
    name: str
    age: int = Field(gt=0)
    email: str | None = None


@app.post("/users")
def create_user(user: UserCreate):
    # リクエストボディから受け取ったユーザーデータをそのまま返す
    return user

正常系の結果

リクエストボディ

{
  "name": "Taro",
  "age": 30,
  "email": "taro@example.com"
}

実行結果

age に 0を指定した結果

ChatGPT先生のレビュー結果

まとめ

今回はPOST APIとPydanticについて学びました。

POSTリクエストのリクエストボディの仕様は、PydanticのBaseModelを継承したクラスを作成して、そこに各項目の型を定義します。FastAPIはこの定義をもとに、リクエストボディの入力値を検証します。

この時にPydanticのField()を使用することで、さらに詳細な条件を指定することができます。

このクラスがそのままAPIのリクエストボディの仕様となり、Swagger UIにも自動で反映されるため、APIドキュメントのために別途実装が必要がないところがとても便利だと感じました。