概要（ドキュメント UI＝「API 仕様書をブラウザで触れる画面」にしたもの）
ドキュメント UI は、
「API の仕様を、人間がブラウザ上で見たり、その場で試したりできる画面」
のことです。
FastAPI だと、アプリを起動した瞬間にすでに二つのドキュメント UI が手に入ります。/docs の Swagger UI と、/redoc の ReDoc です。
どちらも「OpenAPI という API 仕様書」を元にして動いていて、
あなたが FastAPI のコードを書けば書くほど、自動的にリッチになっていきます。
ここから、初心者向けに
ドキュメント UI で何ができるのか
Swagger UI（/docs）の具体的な使い方
ReDoc（/redoc）の見え方の違い
コードのどこが UI にどう反映されるのか
最初に押さえておくべきカスタマイズのポイント
を、例を交えながらかみ砕いて説明します。
ドキュメント UI がある世界とない世界の違いをイメージする
ドキュメント UI がないときの「つらい API 利用」
もしドキュメント UI がないと、API を使う人はこうなります。
どの URL があるか分からないので、README や Excel の仕様書を探す。
その仕様書が古くなっていて、実際の API とズレていることがある。
試したいときは curl や Postman を手で設定してリクエストを送る。
つまり、「仕様」と「実際の挙動」と「テスト」が全部バラバラです。
初心者だと、そもそも「どんなリクエストを投げればいいか」が分からず、
毎回教えてもらう必要が出てきます。
ドキュメント UI があるときの「触って理解できる API」
FastAPI のドキュメント UI がある世界では、流れがまったく変わります。
ブラウザで /docs を開くと、
全てのエンドポイントが一覧で表示される。
エンドポイントをクリックすると、必要な入力やレスポンスの形が図で見える。
その場のフォームに値を入れて「Try it out」ボタンを押すと、実際に API を叩ける。
つまり、
「仕様書」も「テストツール」も「サンプルリクエスト」も、全部ブラウザ一枚で済む
という状態になります。
これが「ドキュメント UI がある」ときの世界です。
Swagger UI（/docs）の見方と使い方
/docs を開いたときに何が見えているか
FastAPI アプリを起動し、ブラウザで http://127.0.0.1:8000/docs にアクセスしてみてください。
上には API のタイトルやバージョン、説明が表示されます。
真ん中にはエンドポイントの一覧が出てきます。GET /items や POST /users といった行ごとに、パスや説明、レスポンスなどがまとまっています。
各エンドポイントの行をクリックすると、詳細が開きます。
そこには次のような情報がまとまっています。
パスパラメータの一覧と型（例: user_id: integer）
クエリパラメータの一覧と型（例: limit: integer, optional）
リクエストボディ（JSON）のスキーマ（どんなフィールドがあるか）
レスポンスの構造（成功時の JSON の形、ステータスコードごとの説明）
これらはすべて、あなたが FastAPI のエンドポイントと Pydantic モデルに書いた情報から、自動で生成されています。
「Try it out」で実際にリクエストを投げてみる
Swagger UI の右上やエンドポイントの中に「Try it out」ボタンがあります。
例えば、次のようなコードがあるとします。
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
price: float
@app.post("/items")
def create_item(item: Item):
return item
/docs を開いて POST /items を展開すると、
リクエストボディの入力欄が自動で表示されます。
「Try it out」を押すと入力欄が編集可能になり、
例えば次のような JSON を入れられます。
{
"name": "Apple",
"price": 100
}
その状態で「Execute」を押すと、
ブラウザから実際に POST /items にリクエストが送られ、
下部にレスポンス（Status code と JSON）が表示されます。
ここで重要なのは、
curl や Postman を触らなくても、
API の使い方を「試しながら覚えられる」ことです。
初心者でも、画面を見ながらパラメータを変えて試せるので、
API の挙動を体で理解しやすくなります。
ReDoc（/redoc）の特徴と Swagger UI との違い
ReDoc は「読みやすさ重視の仕様書ビュー」
同じ FastAPI アプリで、http://127.0.0.1:8000/redoc を開くと、
ReDoc という別のドキュメント UI が表示されます。
左側にエンドポイント一覧のナビゲーション。
右側に選択したエンドポイントの詳細な説明。
レスポンススキーマや例が縦にずらっと並ぶ見やすい構成。
Swagger UI が「試す」ことに向いているのに対して、
ReDoc は「読む」ことに向いている印象です。
ReDoc は「Try it out」のような実行ボタンはありませんが、
複雑なスキーマ（ネストした JSON）や、大量のエンドポイントを
落ち着いて眺めるのに向いています。
チーム内や外部公開用の「読み物としての API ドキュメント」としては、
ReDoc の方が好まれることも多いです。
どちらも中身は同じ OpenAPI を見ている
Swagger UI と ReDoc の違いは「見せ方」だけです。
どちらも、元データとして openapi.json を読んでいます。
FastAPI が生成する OpenAPI スキーマ
それを Swagger UI がインタラクティブな UI に変換
同じものを ReDoc が読み物寄りの UI に変換
この関係さえ押さえておけば OK です。
どちらを主に使うかは好みですが、
開発中は「試せる」Swagger UI（/docs）の方をメインに使うことが多いです。
コードのどこがドキュメント UI に反映されるのか
FastAPI の title, description, version がヘッダ情報になる
FastAPI アプリを作るとき、FastAPI() に引数を渡せます。
app = FastAPI(
title="Sample API",
description="これはサンプルの API です。",
version="1.0.0",
)
これを書くと、
Swagger UI のページタイトルや説明
ReDoc の上部の API 概要
OpenAPI スキーマ内のメタ情報
が、指定した title, description, version に変わります。
つまり、
アプリ全体の「自己紹介文」をここで書く → ドキュメント UI にそのまま反映される
という構造です。
エンドポイントに書いた docstring や summary, description が説明になる
各エンドポイントには、summary や description を指定できます。
@app.get("/items", summary="アイテム一覧を取得", description="登録されているすべてのアイテムを返します。")
def list_items():
...
これを書くと、/docs の GET /items のところに
短い説明（summary）と詳細説明（description）が表示されます。
また、Python の docstring を使うこともできます。
@app.get("/items")
def list_items():
"""
アイテム一覧を取得します。
複数行で詳しく説明を書くこともできます。
"""
...
この場合、docstring が説明としてドキュメント UI に出てきます。
初心者のうちは、
少なくとも summary だけでも日本語で書いておくと、
あとで自分が見返したときに圧倒的に楽になります。
Pydantic モデルのフィールドも UI 上で「スキーマ」として見える
リクエストボディやレスポンスに Pydantic モデルを使うと、
そのフィールド名と型がそのまま UI 上の「Schema」として表示されます。
例えば、
class User(BaseModel):
id: int
name: str
email: str
をレスポンスモデルに使うと、
Swagger UI や ReDoc 上で
id: integer
name: string
email: string
という形で、レスポンスの JSON 構造が視覚的に表示されます。
さらに Field で説明を付けると、その説明も UI に出ます。
from pydantic import BaseModel, Field
class User(BaseModel):
id: int = Field(..., description="ユーザーID")
name: str = Field(..., description="ユーザー名")
email: str = Field(..., description="メールアドレス")
このように、
「モデルの設計」と「ドキュメント」が一体化しているのが FastAPI の強みです。
初心者がまずやるべき「ドキュメント UI を活かす書き方」
1. 必ず /docs を開いて、「自分の API を目で確認」する
FastAPI のコードを書いたら、必ず /docs を一度開いてみてください。
自分が書いたエンドポイントが、どう一覧表示されているか。
パラメータがどう見えているか。
期待したとおりのレスポンススキーマになっているか。
これを視覚的に確認するだけでも、
型やモデルの書き方がどんどん上達します。
「/docs でどう見えるか」を意識しながらコードを書くと、
自然と「使う人から見た API」を設計できるようになります。
2. summary と description を一行ずつでもいいから書く
最初から完璧な日本語で長文を書く必要はありません。
各エンドポイントに対して、
何をする API か、一行で書く
必要なら、注意点や補足を一言足す
これだけでも、ドキュメント UI の分かりやすさが大きく変わります。
自分一人で使うスクリプトでも、
数週間後の自分は「他人」です。
ドキュメント UI の summary や description は、
未来の自分へのメモ書きだと思って書いておくと、かなり役立ちます。
まとめ（ドキュメント UI は「あなたのコードをそのまま仕様書にしてくれる鏡」）
FastAPI のドキュメント UI（Swagger UI / ReDoc）を、初心者目線で整理すると、こうなります。
ドキュメント UI は、API の仕様をブラウザで見やすく表示し、その場で試せる画面であり、FastAPI では /docs（Swagger UI）と /redoc（ReDoc）が最初から用意されている。
どちらも内部的には /openapi.json の OpenAPI スキーマを読んでおり、あなたがエンドポイントや Pydantic モデル、型ヒントを書けば書くほど、自動的にリッチなドキュメントが生成される。
Swagger UI は「Try it out」で実際にリクエストを送れる“実験場”として、ReDoc は読み物としての仕様書ビューとして、それぞれ使い分けられる。
FastAPI の title, description, version、エンドポイントの summary / description、モデルの Field description などを少しずつ書くだけで、ドキュメント UI の分かりやすさは大きく向上する。