Python | Web フレームワーク：OpenAPI

Python
スポンサーリンク

概要（OpenAPI＝「API の設計図を機械と人間で共有するためのフォーマット」）

OpenAPI は、

「この Web API は、どんな URL があって、どんな入力を受け取り、どんなレスポンスを返すのか」

を、機械が読める形でまとめた「設計図」のようなものです。

人間にとっては「API 仕様書」。
コンピュータにとっては「自動でクライアントコードやドキュメントを生成できる元データ」。

Python の Web フレームワーク（特に FastAPI）は、この OpenAPI を自動生成してくれるので、
「ちゃんとエンドポイントとモデルを書くだけで、勝手に仕様書が付いてくる」世界になります。

ここから、
OpenAPI が何を表しているのか
FastAPI がどう OpenAPI を生成しているのか
/ docs（Swagger UI）や / openapi.json の意味
初心者がまずどこを押さえればいいか

を順番に見ていきます。

OpenAPI が表している「API の情報」をイメージする

OpenAPI は JSON（または YAML）形式で、API の情報を細かく記述します。

例えば次のようなことが、全部「機械が読める形」で書かれています。

どんな HTTP メソッドとパスがあるか（例: GET /items, POST /users）
各エンドポイントがどんなパラメータを受け取るか（パスパラメータ、クエリパラメータ、ボディ）
リクエストボディやレスポンスの JSON がどんな形をしているか（スキーマ）
成功時・失敗時にどんなステータスコードを返し、そのときのレスポンスはどういう形か
認証が必要かどうか、どんな認証方式か（Bearer トークンなど）

つまり、「API を使うのに必要な全部の情報」が、1 つの大きな JSON としてまとめられているイメージです。

この「API 仕様を JSON で表現する標準フォーマット」が OpenAPI です。

FastAPI と OpenAPI の関係（書けば書くほど自動で豊かになる）

FastAPI のすごく大きな特徴のひとつが、

「あなたがエンドポイントや Pydantic モデルを普通に書くだけで、
裏で OpenAPI スキーマを自動生成してくれる」

という点です。

とても簡単な FastAPI アプリを例にします。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

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

@app.get("/hello")
def hello():
    return {"message": "hello"}

@app.post("/items")
def create_item(item: Item):
    return item
Python

この状態で開発サーバーを起動し、
ブラウザで http://127.0.0.1:8000/openapi.json にアクセスすると、
長い JSON が表示されます。

これが「このアプリの OpenAPI スキーマ」です。

FastAPI は次の情報を自動的に拾っています。

GET /hello というエンドポイントがあること
POST /items で、リクエストボディに Item 型が必要なこと
Item モデルが name（文字列）と price（数値）を持つこと

あなたは「普通に FastAPI のコードを書いただけ」なのに、
FastAPI はそれをもとに OpenAPI という標準フォーマットの仕様書を構築してくれます。

/docs（Swagger UI）と /redoc は OpenAPI から作られている

FastAPI を起動すると、自動で次の URL も使えるようになります。

http://127.0.0.1:8000/docs
http://127.0.0.1:8000/redoc

/docs は Swagger UI（スワッガー UI）と呼ばれる画面で、
API 一覧・パラメータ・レスポンス例をブラウザ上で確認しつつ、
その場で「実行」までできます。

実はこの Swagger UI は、
内部的には http://127.0.0.1:8000/openapi.json を読み込んでいます。

つまり、

FastAPI が OpenAPI の JSON を作る
→ Swagger UI がその JSON を読み取って
→ 人間が見やすいドキュメント画面に変換している

という流れです。

あなたが追加のコードを書かなくても、

エンドポイントを 1 個追加
→ /openapi.json が更新される
→ /docs の表示も自動で更新される

という仕組みになっています。

OpenAPI は「機械が読める仕様書」。
Swagger UI は「その仕様書を人間に見せるビューア」。

この関係を覚えておくと、全体像がスッと入ってきます。

コードと OpenAPI スキーマがどう対応しているか（FastAPI の自動生成の“肝”）

FastAPI が OpenAPI を作るとき、特に重要なのが「型」と「ルート定義」です。

例えば、先ほどの create_item を少し拡張します。

from typing import List
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    id: int
    name: str
    price: float

fake_db = [
    Item(id=1, name="Apple", price=100),
    Item(id=2, name="Banana", price=80),
]

@app.get("/items", response_model=List[Item])
def list_items():
    return fake_db
Python

ここで FastAPI は次のことを理解します。

GET /items というエンドポイントがある
戻り値は List[Item]（Item の配列）として扱うべき
Item モデルのフィールド名・型（id: int, name: str, price: float）

OpenAPI の中には、ざっくり言うとこんな情報が入ります。

paths セクションに、/items の定義（GET メソッド、レスポンスのスキーマなど）
components.schemas セクションに、Item モデルの定義（id, name, price の型）

/ docs を見ると、
GET /items の説明に「レスポンスボディが Item の配列」として図示されているはずです。

つまり、

あなたが Pydantic モデルに型を書く
→ FastAPI がそれを OpenAPI のスキーマに変換する
→ Swagger UI がそれを見やすく表示する

という三段構造になっています。

「きれいな型付きの API を書けば書くほど、
OpenAPI スキーマとドキュメントが勝手にリッチになる」

これが FastAPI の気持ちよさです。

OpenAPI が役立つ具体的な場面（人間にも機械にも嬉しい）

OpenAPI があると、ただ「/docs が見やすい」以上のメリットが出てきます。

ひとつめは、クライアントコードの自動生成です。

OpenAPI スキーマがあれば、swagger-codegen や openapi-generator などのツールで、
TypeScript や Java、C# などのクライアント SDK を自動生成できます。

つまり、

バックエンド（FastAPI）が OpenAPI を吐く
→ フロントエンドや他のサービスが、その仕様からクライアントを自動生成
→ 「URL 打ち間違え」「パラメータ名の typo」などが減る

という流れが取りやすくなります。

ふたつめは、他チームとのコミュニケーションです。

OpenAPI スキーマ（または /docs の画面）を共有すれば、

「この API、こういうリクエストを投げると、こういうレスポンスが返ってきます」

という情報が、共通の「真実」になります。

仕様書だけ PowerPoint や Excel で書いていて、
コードとズレていく問題を防ぎやすくなります。

みっつめは、テストとの連携です。

OpenAPI をもとに、自動テストの雛形を作ったり、
モックサーバー（本物の API がまだない段階で、仕様どおりの偽物を立てる）を立てたり、
といったこともできます。

OpenAPI は単なる「おまけ」ではなく、
API 開発全体の“軸”になり得る存在です。

初心者がまず押さえておくべき OpenAPI と FastAPI の使い方

最初から OpenAPI の全項目を理解しようとしなくて大丈夫です。
FastAPI と一緒に使う初心者なら、まず次の感覚があれば十分です。

一つめ。
/openapi.json にアクセスすると、「このアプリの API 仕様書（機械用）」が見える。
FastAPI が勝手に生成してくれている。

二つめ。
/docs は、その仕様書を Swagger UI で人間向けに表示したもの。
ここから実際にリクエストを投げて試せる。

三つめ。
エンドポイント関数の定義（HTTP メソッド、パス、引数の型、レスポンスモデル）をちゃんと書くことで、
OpenAPI スキーマがどんどん豊かになり、/docs も自動で更新される。

ここまでを体で覚えたら、
次のステップとして「description や tags などを付けて OpenAPI を少しリッチにする」があります。

例えば、FastAPI の FastAPI() には
title、description、version などを指定できます。

app = FastAPI(
    title="My Awesome API",
    description="これはサンプルの API です。",
    version="1.0.0",
)
Python

これを書くだけで、/docs のタイトルや説明、
/ openapi.json 内のメタ情報も変わります。

API の「自己紹介文」をここで定義している、と考えると分かりやすいです。

まとめ（OpenAPI は「型付きの API 設計を、そのまま仕様書にするための土台」）

Python の Web フレームワーク、とくに FastAPI における OpenAPI を整理すると、こうなります。

OpenAPI は、「この API はどの URL に、どんなリクエストを投げると、どんなレスポンスを返すか」という仕様を JSON/YAML で表現する標準フォーマット。
FastAPI は、エンドポイントの定義や Pydantic モデル、型ヒントから OpenAPI スキーマを自動生成し、それを /openapi.json で公開する。
Swagger UI（/docs）や ReDoc（/redoc）は、この OpenAPI スキーマを読み取って、人間が見やすいドキュメント画面を作っている。
クライアントコード自動生成、他チームとの仕様共有、モックサーバーやテストとの連携など、「API 開発の土台」として OpenAPI が効いてくる。
初心者のうちは、「FastAPI にちゃんと型とモデルを書けば書くほど、勝手に OpenAPI と /docs が充実していく」という感覚を掴むことが一番大切。

スポンサーリンク
タイトルとURLをコピーしました