【Python】@app.post とは？使い方や引数のオプションや@app.post との違いまでわかりやすく解説！

2025.08.26 2025.08.26

PythonでWebアプリケーションを構築する際に、データの送信や登録処理などを扱うのに便利なのが @app.post() デコレーターです。

特に FastAPI でよく使われるこの構文は、HTTP POST リクエストを受け取るエンドポイントを簡単に定義できるという特徴があります。

この記事では、@app.post() の基本的な意味から使い方、引数のオプション、活用シーン、@app.get() との違いまでを、初心者にもわかりやすく丁寧に解説します。

@app.post とは？

@app.post() は、「このURLにPOSTリクエスト（データ送信）が来たら、この関数を実行してください」というルールを作るための仕組みです。

フォームやアプリ、APIクライアントなどから送られてくるデータを受け取り、処理するための“入り口”になります。

たとえば、「新しいユーザーを登録する」「注文を受け付ける」など、何か新しい情報をサーバーに渡すシーンで使われます。

基本の使い方

FastAPIでの基本的な構文は以下の通りです。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    name: str
    email: str

@app.post("/users/")
def create_user(user: User):
    return {"message": f"{user.name} さんを登録しました"}

from fastapi import FastAPI

from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):

email: str

@app.post("/users/")

def create_user(user: User):

return {"message": f"{user.name} さんを登録しました"}

このコードでは、以下のような動作になります：

/users/ というURLに対してPOSTリクエストが送られると、create_user 関数が実行される
リクエストのボディに {"name": "...", "email": "..."} のようなJSONデータを渡す
関数内では user: User の部分でPydanticモデルによる自動バリデーションが行われる
正常なデータであれば、指定のメッセージをJSON形式で返す

このようにPOSTでは「クライアントから送られてくるデータをサーバーで処理する」という用途に特化しています。

具体例①：フォームデータの登録

例えば商品を登録するAPIは次のように書けます。

class Product(BaseModel):
    name: str
    price: float

@app.post("/products/")
def create_product(product: Product):
    return {"name": product.name, "price": product.price}

class Product(BaseModel):

price: float

@app.post("/products/")

def create_product(product: Product):

return {"name": product.name, "price": product.price}

このような構成にすると、POST /products/ に対して以下のようなJSONを送れば登録処理を行えます：

{
  "name": "ペン",
  "price": 150.0
}

{

"name": "ペン",

"price": 150.0

}

データの形式や型が正しいかも自動でチェックしてくれるので、非常に安心です。

具体例②：status_code やドキュメントの説明

さらに @app.post() には色々なオプション引数を指定できます。

@app.post(
    "/products/",
    response_model=Product,
    summary="新しい商品を登録",
    description="商品名と価格を受け取り、新規商品として登録します",
    status_code=201,
    tags=["products"]
)
def create_product(product: Product):
    return product

@app.post(

"/products/",

response_model=Product,

summary="新しい商品を登録",

description="商品名と価格を受け取り、新規商品として登録します",

status_code=201,

tags=["products"]

)

def create_product(product: Product):

return product

response_model=Product：返すデータの型（スキーマ）を定義。ドキュメントにも自動反映
summary や description：Swagger UI上に表示される説明文
status_code=201：成功時のHTTPステータスコードを指定（通常POSTでは「201 Created」）

これにより、APIの仕様書も同時に自動生成されるので、開発者間での共有も非常にスムーズです。

@app.post の主なオプション引数

@app.post() では、エンドポイントに関する様々な設定をオプション引数として指定することができます。

これは「このURLにPOSTリクエストが来たときにどう動くか」「自動生成されるドキュメントにどう表示されるか」といった挙動や見た目をコントロールするための仕組みです。

初心者の方でも使いやすいように、代表的なオプションを以下にまとめます。

オプション名	説明	記述例
`path`	この関数を“どのURLにPOSTされたら”呼ぶかを決める	`@app.post("/users/")`（ローカルなら `http://localhost:8000/users/` にPOSTで実行。※本番は自分のドメインに置換）
`response_model`	返すデータの型（スキーマ）を固定し、自動バリデーション＆ドキュメント反映	`response_model=User`
`tags`	Swagger UI 上でのカテゴリ分け（見やすく整理）	`tags=["ユーザー管理"]`
`summary`	エンドポイントの一言説明（Swaggerの見出しに表示）	`summary="ユーザー登録"`
`description`	詳しい説明。Markdown対応で改行・箇条書き・コード例も可	`description="名前とメールアドレスを受け取り、新しいユーザーを登録します"`
`status_code`	正常時に返すHTTPステータスコード（既定値を上書き）	`status_code=201`（成功時に 201 Created を返す）

以下はこれらのオプションをすべて組み合わせた具体例です：

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    name: str
    email: str

@app.post(
    "/users/",
    response_model=User,
    summary="ユーザー登録",
    description="名前とメールアドレスを受け取り、新しいユーザーを登録します",
    status_code=201,
    tags=["ユーザー管理"]
)
def create_user(user: User):
    return user

from fastapi import FastAPI

from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):

email: str

@app.post(

"/users/",

response_model=User,

summary="ユーザー登録",

description="名前とメールアドレスを受け取り、新しいユーザーを登録します",

status_code=201,

tags=["ユーザー管理"]

)

def create_user(user: User):

return user

このコードのポイントは以下の通りです：

response_model=User
→ 戻り値が必ず User 型（{"name": str, "email": str}）であることを保証。
間違った型を返そうとすると自動的にエラーになります。
summary="ユーザー登録"
→ Swagger UI のAPI一覧画面でわかりやすく表示されます。
description="..."
→ ドキュメントの詳細欄に補足情報や使い方を書けます。Markdownにも対応しているため、整ったAPI説明書になります。
status_code=201
→ データ作成処理では 201 Created を返すのが一般的なので、よりRESTfulな設計になります。
tags=["ユーザー管理"]
→ ドキュメント内でこのAPIが「ユーザー管理」という分類にまとめられます。

このようにオプションを適切に指定することで、FastAPIが自動生成するドキュメント（Swagger UI）をより見やすく、正確で信頼性の高いものにできます。

開発チーム内での仕様共有や、外部にAPIを公開する際にも非常に役立ちます。

@app.get との違い

@app.postと@app.get の違いを整理しておきましょう。

@app.get() は「データを取得する」ためのエンドポイント、@app.post() は「データを送信・登録する」ためのエンドポイントです。

簡単に整理すると以下のようになります：

目的	デコレーター	使うHTTPメソッド
データ取得	`@app.get()`	GET
データ送信・登録	`@app.post()`	POST

また、ブラウザから直接アクセス（URLに貼り付けてEnter）できるのは @app.get() のみです。

@app.post() は curl やフォーム、JavaScript などからのリクエストが必要になります。

活用シーン

@app.post() は以下のような場面で非常に便利です：

ユーザー登録フォームの受け取り
注文や問い合わせの受付
ファイルのアップロード処理
他サービスからのWebhook受信
データベースへの新規データ登録

いずれも「誰かが何かを送ってきて、それを処理したい」場面で使います。

注意点

便利な @app.post() にも注意すべき点があります。

クライアントから渡されたJSONは、必ずPydanticモデルなどで検証を行うこと（セキュリティ対策）
同じURLで @app.post() と @app.get() を併用する場合、HTTPメソッドの違いを意識する必要がある
クライアント側から適切なContent-Type（例：application/json）が指定されていないと、エラーになることがある
リクエストが大量に来ると処理が重くなることがあるため、非同期化やバリデーションの工夫が必要

初心者のうちは「必ずPOSTではモデルを使う」「エラー処理を用意する」ことを意識しましょう。

まとめ

今回は FastAPI でよく使われる @app.post() について、初心者にもわかりやすく丁寧に解説しました。

ポイントをまとめると：

@app.post() は「クライアントから送られてきたデータを処理する関数」を登録する仕組み
JSON形式のリクエストボディを受け取って、Pydanticでバリデーションできる
response_model や summary, description を使えばAPIドキュメントが自動生成される
@app.get() との大きな違いは「GETは取得」「POSTは登録・送信」

FastAPIではほんの数行でPOSTエンドポイントが作れるので、初心者でもすぐに「自分で動くAPI」を作って試せます。

「データを受け取って保存したい」というシンプルな場面から、ぜひ @app.post() を使ってみてください。

APIの仕組みを理解する第一歩になりますよ！