メインコンテンツへスキップ
見出し画像

FastAPI 0.162.1 の変更点、影響するのは同梱のスキル文書を参照している人


    FastAPI 0.162.1 は 2026-11-07 に公開されました。直前のバージョンは 0.162.0 です。
    リリースノートの区分は Docs、Translations、Internal の 3 つです。
    Features や Fixes の区分はありません。
    Docs の変更は、FastAPI のスキルへのパラメータモデルの指針の追加です。

    リリースノート: https://github.com/fastapi/fastapi/releases/tag/0.162.1

    何が変わったか

    • FastAPI のスキルに、パラメータモデルの指針が追加されました(PR #16693 )。

    • 11 言語の翻訳が更新されました。zh-hant、uk、de、pt、fr、tr、ja、zh、hi、es、ru です。

    • Internal に依存の更新が並んでいます。pillow 13.0.0、dnspython 2.9.2、authlib 1.9.1 などです。

    • pytest が 9.2 未満に固定されました。pytest-xdist との互換のためです(PR #16642 )。

    • ドキュメントの FastAPI Cloud のバナーが、一般提供向けに更新されました(PR #16684 )。

    ほかに、スポンサーへの Encore と MicroAuth の追加があります。
    カンファレンスの表示部品と関連スタイルの削除もあります。

    動かして確かめたこと

    環境は Docker の python:3.12-slim コンテナです。パッケージ導入後にネットワークを切断して実行しています。

    導入のコマンドは次のとおりです。

    pip install --quiet fastapi==0.162.1 httpx

    バージョンを表示すると、終了コード 0 で次のように出ます。

    python -c "import fastapi; print(fastapi.__version__)"
    0.162.1

    確認 1: 同梱のスキル文書

    PR #16693 の指針が、導入したパッケージのスキル文書にあるかを確かめました。

    import pathlib
    import fastapi
    
    root = pathlib.Path(fastapi.__file__).parent
    skills = sorted(p for p in root.rglob('*.md') if 'skill' in str(p).lower())
    if not skills:
        print('NO_SKILL_FILE: no skill markdown found under', root)
        raise SystemExit(0)
    
    keywords = ('parameter model', 'parameter models', 'query()]', 'header()]', 'cookie()]')
    for path in skills:
        text = path.read_text(encoding='utf-8', errors='replace')
        lines = text.splitlines()
        hits = [l.strip() for l in lines if any(k in l.lower() for k in keywords)]
        print(f'FILE: {path.relative_to(root.parent)} ({len(lines)} lines)')
        print(f'MATCHES: {len(hits)}')
        for line in hits[:6]:
            print('  ', line[:140])
    python check_skill.py

    終了コードは 0 で、出力は次のとおりです。

    FILE: fastapi/.agents/skills/fastapi/SKILL.md (333 lines)
    MATCHES: 2
       * Parameter models: `Query`, `Header`, `Cookie`, and `Form` support multiple models and optional groups. See [the parameter models reference
       async def create_item(item: Item, project_id: Annotated[int, Query()]):
    FILE: fastapi/.agents/skills/fastapi/references/dependencies.md (144 lines)
    MATCHES: 0
    FILE: fastapi/.agents/skills/fastapi/references/other-tools.md (78 lines)
    MATCHES: 0
    FILE: fastapi/.agents/skills/fastapi/references/parameter-models.md (61 lines)
    MATCHES: 4
       # Parameter Models
       Use `Annotated[Model, Query()]`, `Header()`, `Cookie()`, or `Form()` to group related inputs. Multiple models can coexist with individual pa
       pagination: Annotated[Pagination, Query()],
       date_range: Annotated[DateRange | None, Query()] = None,
    FILE: fastapi/.agents/skills/fastapi/references/path-operations.md (93 lines)
    MATCHES: 0
    FILE: fastapi/.agents/skills/fastapi/references/pydantic.md (93 lines)
    MATCHES: 1
       async def create_item(item: Item, project_id: Annotated[int, Query()]):
    FILE: fastapi/.agents/skills/fastapi/references/responses.md (79 lines)
    MATCHES: 0
    FILE: fastapi/.agents/skills/fastapi/references/streaming.md (106 lines)
    MATCHES: 0

    スキル文書は、パッケージ内の fastapi/.agents/skills/fastapi/ に同梱されています。
    指針のファイルは references/parameter-models.md(61 行)です。
    Annotated[Model, Query()] でまとめる書き方が載っています。

    確認 2: パラメータモデルの動作

    スキル文書が勧める Annotated[Model, Query()] が、0.162.1 で動くかを確かめました。

    from typing import Annotated
    from fastapi import FastAPI, Query
    from fastapi.testclient import TestClient
    from pydantic import BaseModel, Field
    
    class FilterParams(BaseModel):
        model_config = {'extra': 'forbid'}
        limit: int = Field(10, gt=0, le=100)
        tag: str | None = None
    
    app = FastAPI()
    
    @app.get('/items')
    def items(params: Annotated[FilterParams, Query()]):
        return params.model_dump()
    
    client = TestClient(app)
    ok = client.get('/items', params={'limit': 5, 'tag': 'x'})
    print('OK:', ok.status_code, ok.json())
    bad = client.get('/items', params={'limit': 5, 'unknown': 1})
    print('EXTRA_FORBIDDEN:', bad.status_code, bad.json()['detail'][0]['type'])
    schema = app.openapi()['paths']['/items']['get']['parameters']
    print('OPENAPI_PARAMS:', [p['name'] for p in schema])
    python param_model.py

    終了コードは 0 で、出力は次のとおりです。

    /usr/local/lib/python3.12/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
      from starlette.testclient import TestClient as TestClient  # noqa
    OK: 200 {'limit': 5, 'tag': 'x'}
    EXTRA_FORBIDDEN: 422 extra_forbidden
    OPENAPI_PARAMS: ['limit', 'tag']

    正しい値では 200、定義にない unknown を送ると 422 の extra_forbidden が返ります。
    OpenAPI では、モデルの limit と tag が個別のパラメータとして出ています。

    TestClient の読み込み時には StarletteDeprecationWarning が出ています。
    httpx の代わりに httpx2 を入れるよう求める内容です。

    影響を受ける人

    影響を受けるのは、パッケージ同梱のスキル文書を参照している人です。
    場所は fastapi/.agents/skills/fastapi/ で、パラメータモデルの指針が入っています。

    FastAPI のリポジトリへ貢献する人は、Internal の項目を確認してください。
    pytest の 9.2 未満への固定や、pre-commit フックの更新が含まれます。

    スキル文書を使わず、アプリで FastAPI を使うだけの人は、今回の記載範囲に該当する項目はありません。
    日本語ドキュメントを読む人には、ja の翻訳更新(PR #16648 )が関係します。

    非互換の変更

    今回の記載範囲では非互換の変更はありません。

    上げるべきか

    同梱のスキル文書を参照している人は、上げてください。
    それ以外の人は、急いで上げる理由がリリースノートにありません。
    次の定期的な依存更新でまとめて上げれば足ります。

    この手順で解決すること

    対象は 0.162.0 から 0.162.1 への更新です。
    終わると、fastapi.version が 0.162.1 を返します。
    同梱のスキル文書に references/parameter-models.md が含まれた状態になります。

    準備するもの

    • 依存を固定しているファイル: [requirements.txt、pyproject.toml などのパス]

    • スキル文書を読み込ませている設定: [スキル文書のパスを書いている設定ファイル]

    • 戻せる状態: 更新前のロックファイルを git にコミットしておく

    • 既存のテストを実行するコマンド: [テストの実行コマンド]

    アップデート手順

    1. 更新前のバージョンを記録します。

    python -c "import fastapi; print(fastapi.__version__)"
    1. 使っているパッケージマネージャでバージョンを指定して入れます。

    # pip
    pip install fastapi==0.162.1
    
    # uv
    uv add fastapi==0.162.1
    
    # Poetry
    poetry add fastapi==0.162.1
    1. requirements.txt で管理しているなら、行を書き換えます。

    fastapi==0.162.1
    1. バージョンが 0.162.1 になったかを表示します。

    python -c "import fastapi; print(fastapi.__version__)"
    1. スキル文書の参照先がそろっているかを確かめます。

    python -c "import pathlib, fastapi; p = pathlib.Path(fastapi.__file__).parent / '.agents/skills/fastapi/references/parameter-models.md'; print(p.exists())"
    1. 既存のテストを実行します。

    pytest [テストのディレクトリ]
    1. ロックファイルの差分をコミットします。

    git add [依存を固定しているファイル]
    git commit -m "chore: FastAPI を 0.162.1 に上げる"

    動作確認のチェックリスト

    • [ ] fastapi.version が 0.162.1 を返す

    • [ ] fastapi/.agents/skills/fastapi/SKILL.md がある

    • [ ] references/parameter-models.md がある

    • [ ] スキル文書を読み込ませている設定のパスが、上の場所を指している

    • [ ] 既存のテストがすべて通る

    • [ ] Annotated[Model, Query()] の口でモデルを受け取れる

    • [ ] extra='forbid' のモデルで、未定義の値が 422 になる

    • [ ] TestClient 利用時の StarletteDeprecationWarning を把握している

    戻し方

    1. 0.162.0 を指定して入れ直します。

    # pip
    pip install fastapi==0.162.0
    
    # uv
    uv add fastapi==0.162.0
    
    # Poetry
    poetry add fastapi==0.162.0
    1. ロックファイルを更新前のコミットに戻します。

    git restore --source=[更新前のコミット] [依存を固定しているファイル]
    1. バージョンが 0.162.0 に戻ったかを表示します。

    python -c "import fastapi; print(fastapi.__version__)"

    移行が必要な書き方の対応表

    非互換の変更はないため、スキル文書が勧めるパラメータモデルの使用例を並べます。

    • これまでの書き方: クエリを引数ごとに受け取る

    from typing import Annotated
    from fastapi import FastAPI, Query
    
    app = FastAPI()
    
    @app.get('/items')
    def items(
        limit: Annotated[int, Query(gt=0, le=100)] = 10,
        tag: Annotated[str | None, Query()] = None,
    ):
        return {'limit': limit, 'tag': tag}
    • これからの書き方: モデルにまとめて Annotated[Model, Query()] で受け取る

    from typing import Annotated
    from fastapi import FastAPI, Query
    from pydantic import BaseModel, Field
    
    class FilterParams(BaseModel):
        model_config = {'extra': 'forbid'}
        limit: int = Field(10, gt=0, le=100)
        tag: str | None = None
    
    app = FastAPI()
    
    @app.get('/items')
    def items(params: Annotated[FilterParams, Query()]):
        return params.model_dump()
    • スキル文書に載っている対象: Query、Header、Cookie、Form

    • 検証用のコンテナでの結果: 未定義の値は 422 extra_forbidden

    • 検証用のコンテナでの OpenAPI: limit と tag に展開

    出典

     
     

    io

     
     

    あなたへのおすすめ