diff --git a/docs/ja/docs/advanced/additional-responses.md b/docs/ja/docs/advanced/additional-responses.md index 4c44257885..1d7c2f80e1 100644 --- a/docs/ja/docs/advanced/additional-responses.md +++ b/docs/ja/docs/advanced/additional-responses.md @@ -243,5 +243,5 @@ new_dict = {**old_dict, "new key": "new value"} レスポンスに正確に何を含められるかは、OpenAPI 仕様の次のセクションを参照してください: -- OpenAPI の Responses Object。ここには `Response Object` が含まれます。 -- OpenAPI の Response Object。`responses` パラメータ内の各レスポンスに、ここで定義されている要素を直接含められます。`description`、`headers`、`content`（ここで異なるメディアタイプや JSON Schema を宣言します）、`links` など。 +- [OpenAPI の Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object)、ここには `Response Object` が含まれます。 +- [OpenAPI の Response Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object)、`responses` パラメータ内の各レスポンスに、ここで定義されている要素を直接含められます。`description`、`headers`、`content`（ここで異なるメディアタイプや JSON Schema を宣言します）、`links` など。 diff --git a/docs/ja/docs/advanced/additional-status-codes.md b/docs/ja/docs/advanced/additional-status-codes.md index fdac52e837..ad9bd57dcd 100644 --- a/docs/ja/docs/advanced/additional-status-codes.md +++ b/docs/ja/docs/advanced/additional-status-codes.md @@ -38,4 +38,4 @@ 追加のステータスコードとレスポンスを直接返す場合、それらは OpenAPI スキーマ（API ドキュメント）には含まれません。FastAPI には、事前に何が返されるかを知る方法がないからです。 -しかし、[追加のレスポンス](additional-responses.md){.internal-link target=_blank} を使ってコード内にドキュメント化できます。 +しかし、[追加のレスポンス](additional-responses.md) を使ってコード内にドキュメント化できます。 diff --git a/docs/ja/docs/advanced/advanced-dependencies.md b/docs/ja/docs/advanced/advanced-dependencies.md index d38ce548d1..5181e39d82 100644 --- a/docs/ja/docs/advanced/advanced-dependencies.md +++ b/docs/ja/docs/advanced/advanced-dependencies.md @@ -132,7 +132,7 @@ SQLModel（または SQLAlchemy）でこの特定のユースケースがある このようにすると、セッションはデータベース接続を解放するため、他のリクエストがそれを使えるようになります。 -`yield` を持つ依存関係で早期終了が必要な別のユースケースがある場合は、あなたの具体的なユースケースと、なぜ `yield` を持つ依存関係の早期クローズが有益かを説明して、GitHub Discussion の質問を作成してください。 +`yield` を持つ依存関係で早期終了が必要な別のユースケースがある場合は、あなたの具体的なユースケースと、なぜ `yield` を持つ依存関係の早期クローズが有益かを説明して、[GitHub Discussion の質問](https://github.com/fastapi/fastapi/discussions/new?category=questions)を作成してください。 `yield` を持つ依存関係の早期クローズに納得できるユースケースがある場合は、早期クローズにオプトインする新しい方法を追加することを検討します。 @@ -144,7 +144,7 @@ FastAPI 0.110.0 より前では、`yield` を持つ依存関係を使い、そ ### バックグラウンドタスクと `yield` を伴う依存関係、技術詳細 { #background-tasks-and-dependencies-with-yield-technical-details } -FastAPI 0.106.0 より前では、`yield` の後で例外を送出することはできませんでした。`yield` を持つ依存関係の終了コードはレスポンス送信「後」に実行されるため、[例外ハンドラ](../tutorial/handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank} はすでに実行済みでした。 +FastAPI 0.106.0 より前では、`yield` の後で例外を送出することはできませんでした。`yield` を持つ依存関係の終了コードはレスポンス送信「後」に実行されるため、[例外ハンドラ](../tutorial/handling-errors.md#install-custom-exception-handlers)はすでに実行済みでした。 これは主に、依存関係が "yield" した同じオブジェクトをバックグラウンドタスク内で利用できるようにするための設計でした。終了コードはバックグラウンドタスク完了後に実行されるからです。 diff --git a/docs/ja/docs/advanced/async-tests.md b/docs/ja/docs/advanced/async-tests.md index 067e9cc9a2..076688d67e 100644 --- a/docs/ja/docs/advanced/async-tests.md +++ b/docs/ja/docs/advanced/async-tests.md @@ -16,7 +16,7 @@ `TestClient` は、標準の pytest を使って通常の `def` のテスト関数から非同期の FastAPI アプリを呼び出すための「おまじない」を内部で行います。しかし、その「おまじない」はテスト関数自体が非同期の場合には機能しません。テストを非同期で実行すると、テスト関数内で `TestClient` は使えなくなります。 -`TestClient` は HTTPX を基に作られており、幸いなことに API のテストには HTTPX を直接利用できます。 +`TestClient` は [HTTPX](https://www.python-httpx.org) を基に作られており、幸いなことに API のテストには HTTPX を直接利用できます。 ## 例 { #example } @@ -60,7 +60,7 @@ $ pytest /// tip | 豆知識 -`TestClient` を使っていたときと異なり、テスト関数は `def` ではなく `async def` になっている点に注意してください。 +`TestClient` を使っていたときと異なり、テスト関数は `async def` ではなく `def` になっている点に注意してください。 /// @@ -84,7 +84,7 @@ response = client.get('/') /// warning | 注意 -アプリケーションが lifespan イベントに依存している場合、`AsyncClient` はそれらのイベントをトリガーしません。確実にトリガーするには、florimondmanca/asgi-lifespan の `LifespanManager` を使用してください。 +アプリケーションが lifespan イベントに依存している場合、`AsyncClient` はそれらのイベントをトリガーしません。確実にトリガーするには、[florimondmanca/asgi-lifespan](https://github.com/florimondmanca/asgi-lifespan#usage) の `LifespanManager` を使用してください。 /// @@ -94,6 +94,6 @@ response = client.get('/') /// tip | 豆知識 -テストに非同期関数呼び出しを統合した際に（例: MongoDB の MotorClient 使用時）、`RuntimeError: Task attached to a different loop` に遭遇した場合は、イベントループを必要とするオブジェクトは非同期関数内でのみインスタンス化するようにしてください。例えば `@app.on_event("startup")` コールバック内で行います。 +テストに非同期関数呼び出しを統合した際に（例: [MongoDB の MotorClient](https://stackoverflow.com/questions/41584243/runtimeerror-task-attached-to-a-different-loop) 使用時）、`RuntimeError: Task attached to a different loop` に遭遇した場合は、イベントループを必要とするオブジェクトは非同期関数内でのみインスタンス化するようにしてください。例えば `@app.on_event("startup")` コールバック内で行います。 /// diff --git a/docs/ja/docs/advanced/behind-a-proxy.md b/docs/ja/docs/advanced/behind-a-proxy.md index 67eaa99092..178713fb8f 100644 --- a/docs/ja/docs/advanced/behind-a-proxy.md +++ b/docs/ja/docs/advanced/behind-a-proxy.md @@ -16,9 +16,9 @@ プロキシのヘッダーは次のとおりです: -* X-Forwarded-For -* X-Forwarded-Proto -* X-Forwarded-Host +* [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-For) +* [X-Forwarded-Proto](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-Proto) +* [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-Host) /// @@ -228,7 +228,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 サーバー（Uvicorn）は、その `root_path` をアプリに渡す以外の用途では使用しない点に注意してください。 -しかし、ブラウザで http://127.0.0.1:8000/app にアクセスすると、通常どおりのレスポンスが表示されます: +しかし、ブラウザで [http://127.0.0.1:8000/app](http://127.0.0.1:8000/app) にアクセスすると、通常どおりのレスポンスが表示されます: ```JSON { @@ -251,9 +251,9 @@ Uvicorn は、プロキシが `http://127.0.0.1:8000/app` にアクセスして ## Traefik を使ったローカル検証 { #testing-locally-with-traefik } -Traefik を使えば、パスプレフィックスを削除する構成をローカルで簡単に試せます。 +[Traefik](https://docs.traefik.io/) を使えば、パスプレフィックスを削除する構成をローカルで簡単に試せます。 -Traefik をダウンロード してください。単一バイナリなので、圧縮ファイルを展開して端末から直接実行できます。 +[Traefik をダウンロード](https://github.com/containous/traefik/releases) してください。単一バイナリなので、圧縮ファイルを展開して端末から直接実行できます。 次の内容で `traefik.toml` というファイルを作成します: @@ -330,7 +330,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 ### レスポンスの確認 { #check-the-responses } -ここで、Uvicorn のポートの URL http://127.0.0.1:8000/app にアクセスすると、通常どおりのレスポンスが表示されます: +ここで、Uvicorn のポートの URL [http://127.0.0.1:8000/app](http://127.0.0.1:8000/app) にアクセスすると、通常どおりのレスポンスが表示されます: ```JSON { @@ -345,7 +345,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 /// -次に、Traefik のポートでプレフィックス付きの URL http://127.0.0.1:9999/api/v1/app を開きます。 +次に、Traefik のポートでプレフィックス付きの URL [http://127.0.0.1:9999/api/v1/app](http://127.0.0.1:9999/api/v1/app) を開きます。 同じレスポンスが得られます: @@ -370,13 +370,13 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 「公式な」アクセス方法は、定義したパスプレフィックス付きのプロキシ経由です。したがって想定どおり、プレフィックスなしの URL で Uvicorn が直接提供するドキュメント UI にアクセスすると動作しません。プロキシ経由でアクセスされることを前提としているためです。 -http://127.0.0.1:8000/docs を確認してください: +[http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) を確認してください: しかし、プロキシ（ポート `9999`）を使った「公式」URL `/api/v1/docs` でドキュメント UI にアクセスすると、正しく動作します！🎉 -http://127.0.0.1:9999/api/v1/docs を確認してください: +[http://127.0.0.1:9999/api/v1/docs](http://127.0.0.1:9999/api/v1/docs) を確認してください: @@ -433,7 +433,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 /// -ドキュメント UI（http://127.0.0.1:9999/api/v1/docs）では次のように表示されます: +ドキュメント UI（[http://127.0.0.1:9999/api/v1/docs](http://127.0.0.1:9999/api/v1/docs)）では次のように表示されます: diff --git a/docs/ja/docs/advanced/custom-response.md b/docs/ja/docs/advanced/custom-response.md index 50a7891658..e66b1f4944 100644 --- a/docs/ja/docs/advanced/custom-response.md +++ b/docs/ja/docs/advanced/custom-response.md @@ -1,150 +1,134 @@ -# カスタムレスポンス - HTML、ストリーム、ファイル、その他のレスポンス { #custom-response-html-stream-file-others } +# カスタムレスポンス - HTML、ストリーム、ファイル、その他 { #custom-response-html-stream-file-others } -デフォルトでは、**FastAPI** は `JSONResponse` を使ってレスポンスを返します。 +デフォルトでは、**FastAPI** はJSONレスポンスを返します。 -[レスポンスを直接返す](response-directly.md){.internal-link target=_blank}で見たように、 `Response` を直接返すことでこの挙動をオーバーライドできます。 +[レスポンスを直接返す](response-directly.md)で見たように、`Response` を直接返してこの挙動を上書きできます。 -しかし、`Response` を直接返すと（または `JSONResponse` のような任意のサブクラスを返すと）、データは自動的に変換されず（`response_model` を宣言していても）、ドキュメントも自動生成されません（例えば、生成されるOpenAPIの一部としてHTTPヘッダー `Content-Type` に特定の「メディアタイプ」を含めるなど）。 +しかし、`Response`（または `JSONResponse` のような任意のサブクラス）を直接返す場合、（`response_model` を宣言していても）データは自動的に変換されず、ドキュメントも自動生成されません（例えば、生成されるOpenAPIの一部としてHTTPヘッダー `Content-Type` に特定の「メディアタイプ」を含めるなど）。 -`response_class` パラメータを使用して、*path operation デコレータ* で使用したい `Response`（任意の `Response` サブクラス）を宣言することもできます。 +一方で、*path operation デコレータ* の `response_class` パラメータを使って、使用したい `Response`（`Response` の任意のサブクラス）を宣言することもできます。 -*path operation 関数* から返されるコンテンツは、その `Response` に含まれます。 - -そしてその `Response` が、`JSONResponse` や `UJSONResponse` の場合のようにJSONメディアタイプ（`application/json`）なら、関数の返り値は *path operationデコレータ* に宣言した任意のPydantic `response_model` により自動的に変換（およびフィルタ）されます。 +*path operation 関数* から返したコンテンツは、その `Response` に格納されます。 /// note | 備考 -メディアタイプを指定せずにレスポンスクラスを利用すると、FastAPIはレスポンスにコンテンツがないことを期待します。そのため、生成されるOpenAPIドキュメントにレスポンスフォーマットが記載されません。 +メディアタイプを持たないレスポンスクラスを使用すると、FastAPIはレスポンスにコンテンツがないものと見なします。そのため、生成されるOpenAPIドキュメントにレスポンスフォーマットは記載されません。 /// -## `ORJSONResponse` を使う { #use-orjsonresponse } - -例えば、パフォーマンスを絞り出したい場合は、`orjson`をインストールし、レスポンスとして `ORJSONResponse` をセットできます。 - -使いたい `Response` クラス（サブクラス）をインポートし、*path operationデコレータ* に宣言します。 +## JSONレスポンス { #json-responses } -大きなレスポンスの場合、`Response` を直接返すほうが、辞書を返すよりもはるかに高速です。 +FastAPI はデフォルトでJSONレスポンスを返します。 -これは、デフォルトではFastAPIがチュートリアルで説明した同じ[JSON Compatible Encoder](../tutorial/encoder.md){.internal-link target=_blank}を使って、内部の各アイテムを検査し、JSONとしてシリアライズ可能であることを確認するためです。これにより、例えばデータベースモデルのような**任意のオブジェクト**を返せます。 +[レスポンスモデル](../tutorial/response-model.md) を宣言すると、FastAPI は Pydantic を使ってデータをJSONにシリアライズします。 -しかし、返そうとしているコンテンツが **JSONでシリアライズ可能**であることが確実なら、それを直接レスポンスクラスに渡して、FastAPIがレスポンスクラスへ渡す前に返却コンテンツを `jsonable_encoder` に通すことで発生する追加のオーバーヘッドを回避できます。 - -{* ../../docs_src/custom_response/tutorial001b_py310.py hl[2,7] *} - -/// info | 情報 +レスポンスモデルを宣言しない場合、FastAPI は [JSON Compatible Encoder](../tutorial/encoder.md) で説明した `jsonable_encoder` を使い、その結果を `JSONResponse` に入れます。 -パラメータ `response_class` は、レスポンスの「メディアタイプ」を定義するためにも利用されます。 +`JSONResponse` のようにJSONメディアタイプ（`application/json`）を持つ `response_class` を宣言した場合、*path operation デコレータ* に宣言した任意のPydanticの `response_model` に従って、返すデータは自動的に変換（およびフィルタ）されます。ただし、そのデータは Pydantic でJSONのバイト列にシリアライズされるわけではなく、まず `jsonable_encoder` で変換された後に `JSONResponse` クラスへ渡され、Pythonの標準JSONライブラリでバイト列にシリアライズされます。 -この場合、HTTPヘッダー `Content-Type` には `application/json` がセットされます。 - -そして、OpenAPIにはそのようにドキュメントされます。 - -/// - -/// tip | 豆知識 +### JSONのパフォーマンス { #json-performance } -`ORJSONResponse` はFastAPIでのみ利用可能で、Starletteでは利用できません。 +結論として、最大のパフォーマンスを得たい場合は、[レスポンスモデル](../tutorial/response-model.md) を使い、*path operation デコレータ* で `response_class` は宣言しないでください。 -/// +{* ../../docs_src/response_model/tutorial001_01_py310.py ln[15:17] hl[16] *} ## HTMLレスポンス { #html-response } -**FastAPI** からHTMLを直接返す場合は、`HTMLResponse` を使います。 +**FastAPI** からHTMLを直接返すには、`HTMLResponse` を使います。 -* `HTMLResponse` をインポートする。 -* *path operation デコレータ* のパラメータ `response_class` に `HTMLResponse` を渡す。 +* `HTMLResponse` をインポートする +* *path operation デコレータ* のパラメータ `response_class` に `HTMLResponse` を渡す {* ../../docs_src/custom_response/tutorial002_py310.py hl[2,7] *} /// info | 情報 -パラメータ `response_class` は、レスポンスの「メディアタイプ」を定義するためにも利用されます。 +パラメータ `response_class` は、レスポンスの「メディアタイプ」を定義するためにも使用されます。 -この場合、HTTPヘッダー `Content-Type` には `text/html` がセットされます。 +この場合、HTTPヘッダー `Content-Type` には `text/html` が設定されます。 -そして、OpenAPIにはそのようにドキュメントされます。 +そして、OpenAPIにもそのようにドキュメント化されます。 /// ### `Response` を返す { #return-a-response } -[レスポンスを直接返す](response-directly.md){.internal-link target=_blank}で見たように、レスポンスを返すことで、*path operation* の中でレスポンスを直接オーバーライドすることもできます。 +[レスポンスを直接返す](response-directly.md)で見たように、*path operation* の中でレスポンスを直接返して上書きすることもできます。 -上記と同じ例において、 `HTMLResponse` を返すと、このようになります: +上記と同じ例で、`HTMLResponse` を返すと次のようになります: {* ../../docs_src/custom_response/tutorial003_py310.py hl[2,7,19] *} /// warning | 注意 -*path operation関数* から直接返される `Response` は、OpenAPIにドキュメントされず（例えば、`Content-Type` がドキュメントされない）、自動的な対話的ドキュメントでも表示されません。 +*path operation 関数* から直接返される `Response` は、OpenAPIにドキュメント化されず（例えば `Content-Type` がドキュメント化されない）、自動生成の対話的ドキュメントにも表示されません。 /// /// info | 情報 -もちろん、実際の `Content-Type` ヘッダーやステータスコードなどは、返された `Response` オブジェクトに由来します。 +もちろん、実際の `Content-Type` ヘッダーやステータスコードなどは、返した `Response` オブジェクトに由来します。 /// -### OpenAPIドキュメントと `Response` のオーバーライド { #document-in-openapi-and-override-response } +### OpenAPIにドキュメント化しつつ `Response` を上書き { #document-in-openapi-and-override-response } -関数の中でレスポンスをオーバーライドしつつも、OpenAPI に「メディアタイプ」をドキュメント化したいなら、`response_class` パラメータを使用し、かつ `Response` オブジェクトを返します。 +関数の中からレスポンスを上書きしつつ、同時にOpenAPIで「メディアタイプ」をドキュメント化したい場合は、`response_class` パラメータを使用し、かつ `Response` オブジェクトを返します。 -`response_class` はOpenAPIの*path operation*のドキュメント化のためにのみ使用され、`Response` はそのまま使用されます。 +この場合、`response_class` はOpenAPIの *path operation* をドキュメント化するためだけに使われ、実際には返した `Response` がそのまま使用されます。 #### `HTMLResponse` を直接返す { #return-an-htmlresponse-directly } -例えば、このようになります: +例えば、次のようになります: {* ../../docs_src/custom_response/tutorial004_py310.py hl[7,21,23] *} -この例では、関数 `generate_html_response()` は、`str` のHTMLを返すのではなく、`Response` を生成して返しています。 +この例では、関数 `generate_html_response()` はHTMLの `str` を返すのではなく、すでに `Response` を生成して返しています。 -`generate_html_response()` を呼び出した結果を返すことにより、デフォルトの **FastAPI** の挙動をオーバーライドする `Response` をすでに返しています。 +`generate_html_response()` の呼び出し結果を返すことで、デフォルトの **FastAPI** の挙動を上書きする `Response` をすでに返しています。 -しかし、`response_class` にも `HTMLResponse` を渡しているため、**FastAPI** はOpenAPIと対話的ドキュメントで、`text/html` のHTMLとしてどのようにドキュメント化すればよいかを理解できます: +しかし、`response_class` にも `HTMLResponse` を渡しているため、**FastAPI** はOpenAPIおよび対話的ドキュメントで、それが `text/html` のHTMLであると正しくドキュメント化できます: ## 利用可能なレスポンス { #available-responses } -以下が利用可能なレスポンスの一部です。 +以下は利用可能なレスポンスの一部です。 -`Response` を使って他の何かを返せますし、カスタムのサブクラスも作れることを覚えておいてください。 +`Response` を使って他のものを返したり、カスタムサブクラスを作成することもできます。 /// note | 技術詳細 -`from starlette.responses import HTMLResponse` も利用できます。 +`from starlette.responses import HTMLResponse` を使うこともできます。 -**FastAPI** は開発者の利便性のために、`starlette.responses` と同じものを `fastapi.responses` として提供しています。しかし、利用可能なレスポンスのほとんどはStarletteから直接提供されます。 +**FastAPI** は開発者の利便性のために、`starlette.responses` と同じものを `fastapi.responses` として提供しています。ただし、利用可能なレスポンスの多くはStarletteから直接提供されています。 /// ### `Response` { #response } -メインの `Response` クラスで、他の全てのレスポンスはこれを継承しています。 +メインの `Response` クラスで、他のすべてのレスポンスはこれを継承しています。 直接返すことができます。 以下のパラメータを受け付けます。 -* `content` - `str` か `bytes`。 -* `status_code` - `int` のHTTPステータスコード。 -* `headers` - 文字列の `dict` 。 -* `media_type` - メディアタイプを示す `str` 。例えば `"text/html"` 。 +* `content` - `str` または `bytes` +* `status_code` - `int` のHTTPステータスコード +* `headers` - 文字列の `dict` +* `media_type` - メディアタイプを示す `str`。例: `"text/html"` -FastAPI（実際にはStarlette）は自動的にContent-Lengthヘッダーを含みます。また、`media_type` に基づいたContent-Typeヘッダーを含み、テキストタイプのためにcharsetを追加します。 +FastAPI（実際にはStarlette）は自動的に Content-Length ヘッダーを含めます。また、`media_type` に基づいた Content-Type ヘッダーを含め、テキストタイプには charset を追加します。 {* ../../docs_src/response_directly/tutorial002_py310.py hl[1,18] *} ### `HTMLResponse` { #htmlresponse } -上で読んだように、テキストやバイトを受け取り、HTMLレスポンスを返します。 +上で読んだように、テキストやバイト列を受け取り、HTMLレスポンスを返します。 ### `PlainTextResponse` { #plaintextresponse } -テキストやバイトを受け取り、プレーンテキストのレスポンスを返します。 +テキストやバイト列を受け取り、プレーンテキストのレスポンスを返します。 {* ../../docs_src/custom_response/tutorial005_py310.py hl[2,7,9] *} @@ -152,45 +136,19 @@ FastAPI（実際にはStarlette）は自動的にContent-Lengthヘッダーを データを受け取り、`application/json` としてエンコードされたレスポンスを返します。 -上で読んだように、**FastAPI** のデフォルトのレスポンスとして利用されます。 - -### `ORJSONResponse` { #orjsonresponse } - -上で読んだように、`orjson`を使った、高速な代替のJSONレスポンスです。 - -/// info | 情報 - -これは、例えば `pip install orjson` で `orjson` をインストールする必要があります。 +これは、上で述べたように **FastAPI** のデフォルトのレスポンスです。 -/// - -### `UJSONResponse` { #ujsonresponse } - -`ujson`を使った、代替のJSONレスポンスです。 - -/// info | 情報 - -これは、例えば `pip install ujson` で `ujson` をインストールする必要があります。 - -/// - -/// warning | 注意 - -`ujson` は、いくつかのエッジケースの取り扱いについて、Pythonにビルトインされた実装ほど注意深くありません。 - -/// - -{* ../../docs_src/custom_response/tutorial001_py310.py hl[2,7] *} +/// note | 技術詳細 -/// tip | 豆知識 +ただし、レスポンスモデルや返却型を宣言した場合は、それが直接データのJSONシリアライズに使われ、適切なJSONのメディアタイプを持つレスポンスが `JSONResponse` クラスを使わずに直接返されます。 -`ORJSONResponse` のほうが高速な代替かもしれません。 +これが最適なパフォーマンスを得る理想的な方法です。 /// ### `RedirectResponse` { #redirectresponse } -HTTPリダイレクトを返します。デフォルトでは307ステータスコード（Temporary Redirect）となります。 +HTTPリダイレクトを返します。デフォルトでは307ステータスコード（Temporary Redirect）を使用します。 `RedirectResponse` を直接返せます: @@ -202,56 +160,50 @@ HTTPリダイレクトを返します。デフォルトでは307ステータス {* ../../docs_src/custom_response/tutorial006b_py310.py hl[2,7,9] *} -その場合、*path operation*関数からURLを直接返せます。 +その場合、*path operation* 関数からURLを直接返せます。 -この場合に使用される `status_code` は `RedirectResponse` のデフォルトである `307` になります。 +この場合に使用される `status_code` は、`RedirectResponse` のデフォルトである `307` になります。 --- -また、`status_code` パラメータを `response_class` パラメータと組み合わせて使うこともできます: +さらに、`status_code` パラメータを `response_class` パラメータと組み合わせて使うこともできます: {* ../../docs_src/custom_response/tutorial006c_py310.py hl[2,7,9] *} ### `StreamingResponse` { #streamingresponse } -非同期ジェネレータ、または通常のジェネレータ/イテレータを受け取り、レスポンスボディをストリームします。 +非同期ジェネレータ、または通常のジェネレータ/イテレータ（`yield` を持つ関数）を受け取り、レスポンスボディをストリームします。 -{* ../../docs_src/custom_response/tutorial007_py310.py hl[2,14] *} +{* ../../docs_src/custom_response/tutorial007_py310.py hl[3,16] *} -#### ファイルライクオブジェクトで `StreamingResponse` を使う { #using-streamingresponse-with-file-like-objects } - -file-like オブジェクト（例: `open()` で返されるオブジェクト）がある場合、そのfile-likeオブジェクトを反復処理するジェネレータ関数を作れます。 - -そうすれば、最初にすべてをメモリへ読み込む必要はなく、そのジェネレータ関数を `StreamingResponse` に渡して返せます。 - -これにはクラウドストレージとの連携、映像処理など、多くのライブラリが含まれます。 +/// note | 技術詳細 -{* ../../docs_src/custom_response/tutorial008_py310.py hl[2,10:12,14] *} +`async` タスクは `await` に到達したときにのみキャンセルできます。`await` がない場合、ジェネレータ（`yield` を持つ関数）は適切にキャンセルできず、キャンセル要求後も実行が続く可能性があります。 -1. これはジェネレータ関数です。内部に `yield` 文を含むため「ジェネレータ関数」です。 -2. `with` ブロックを使うことで、ジェネレータ関数が終わった後（つまりレスポンスの送信が完了した後）にfile-likeオブジェクトが確実にクローズされるようにします。 -3. この `yield from` は、`file_like` という名前のものを反復処理するように関数へ指示します。そして反復された各パートについて、そのパートをこのジェネレータ関数（`iterfile`）から来たものとして `yield` します。 +この小さな例では `await` が不要なため、イベントループにキャンセルを処理する機会を与えるために `await anyio.sleep(0)` を追加しています。 - つまり、内部的に「生成」の作業を別のものへ移譲するジェネレータ関数です。 +これは大きなストリームや無限ストリームではさらに重要になります。 - このようにすることで `with` ブロックに入れられ、完了後にfile-likeオブジェクトが確実にクローズされます。 +/// /// tip | 豆知識 -ここでは `async` と `await` をサポートしていない標準の `open()` を使っているため、通常の `def` でpath operationを宣言している点に注意してください。 +`StreamingResponse` を直接返す代わりに、[データをストリームする](./stream-data.md) スタイルに従うことをおすすめします。こちらのほうがはるかに便利で、裏側でキャンセル処理も行ってくれます。 + +JSON Lines をストリームする場合は、[JSON Lines をストリームする](../tutorial/stream-json-lines.md) チュートリアルを参照してください。 /// ### `FileResponse` { #fileresponse } -レスポンスとしてファイルを非同期的にストリームします。 +ファイルをレスポンスとして非同期にストリームします。 -他のレスポンスタイプとは異なる引数のセットを受け取りインスタンス化します。 +他のレスポンスタイプとは異なる引数セットでインスタンス化します: -* `path` - ストリームするファイルのファイルパス。 -* `headers` - 含めたい任意のカスタムヘッダーの辞書。 -* `media_type` - メディアタイプを示す文字列。未設定の場合、ファイル名やパスからメディアタイプが推測されます。 -* `filename` - 設定した場合、レスポンスの `Content-Disposition` に含まれます。 +* `path` - ストリームするファイルのファイルパス +* `headers` - 含めたい任意のカスタムヘッダー（辞書） +* `media_type` - メディアタイプを示す文字列。未設定の場合、ファイル名やパスから推測されます +* `filename` - 設定した場合、レスポンスの `Content-Disposition` に含まれます ファイルレスポンスには、適切な `Content-Length`、`Last-Modified`、`ETag` ヘッダーが含まれます。 @@ -261,17 +213,17 @@ HTTPリダイレクトを返します。デフォルトでは307ステータス {* ../../docs_src/custom_response/tutorial009b_py310.py hl[2,8,10] *} -この場合、*path operation*関数からファイルパスを直接返せます。 +この場合、*path operation* 関数からファイルパスを直接返せます。 ## カスタムレスポンスクラス { #custom-response-class } -`Response` を継承した独自のカスタムレスポンスクラスを作成して利用できます。 +`Response` を継承して、独自のカスタムレスポンスクラスを作成し、使用できます。 -例えば、`orjson`を使いたいが、同梱の `ORJSONResponse` クラスで使われていないカスタム設定も使いたいとします。 +例えば、[`orjson`](https://github.com/ijl/orjson) を特定の設定で使いたいとします。 -例えば、インデントされ整形されたJSONを返したいので、orjsonオプション `orjson.OPT_INDENT_2` を使いたいとします。 +インデントされた整形済みJSONを返したいので、orjson のオプション `orjson.OPT_INDENT_2` を使いたいとします。 -`CustomORJSONResponse` を作れます。主に必要なのは、コンテンツを `bytes` として返す `Response.render(content)` メソッドを作ることです: +`CustomORJSONResponse` を作成できます。主に必要なのは、`bytes` を返す `Response.render(content)` メソッドを作ることです: {* ../../docs_src/custom_response/tutorial009c_py310.py hl[9:14,17] *} @@ -289,24 +241,32 @@ HTTPリダイレクトを返します。デフォルトでは307ステータス } ``` -もちろん、JSONの整形よりも、これを活用するもっと良い方法が見つかるはずです。 😉 +もちろん、JSONの整形以外にも、これを活用するもっと良い方法が見つかるはずです。 😉 + +### `orjson` か レスポンスモデルか { #orjson-or-response-model } + +もし求めているのがパフォーマンスであれば、`orjson` レスポンスを使うより、[レスポンスモデル](../tutorial/response-model.md) を使うほうが良い場合が多いです。 + +レスポンスモデルがあると、FastAPI は中間ステップ（他の場合に行われる `jsonable_encoder` による変換など）を介さずに、Pydantic を使ってデータをJSONにシリアライズします。 + +内部的には、Pydantic はJSONシリアライズに `orjson` と同じRust由来の仕組みを用いているため、レスポンスモデルを使うだけで最良のパフォーマンスが得られます。 ## デフォルトレスポンスクラス { #default-response-class } -**FastAPI** クラスのインスタンス、または `APIRouter` を作成する際に、デフォルトで使用するレスポンスクラスを指定できます。 +**FastAPI** クラスのインスタンスや `APIRouter` を作成する際に、デフォルトで使用するレスポンスクラスを指定できます。 これを定義するパラメータは `default_response_class` です。 -以下の例では、**FastAPI** はすべての*path operation*で、`JSONResponse` の代わりに `ORJSONResponse` をデフォルトとして使います。 +以下の例では、**FastAPI** はすべての *path operation* で、JSONの代わりにデフォルトで `HTMLResponse` を使用します。 {* ../../docs_src/custom_response/tutorial010_py310.py hl[2,4] *} /// tip | 豆知識 -これまでと同様に、*path operation*で `response_class` をオーバーライドできます。 +これまでと同様に、*path operation* ごとに `response_class` をオーバーライドできます。 /// ## その他のドキュメント { #additional-documentation } -OpenAPIでは `responses` を使ってメディアタイプやその他の詳細を宣言することもできます: [Additional Responses in OpenAPI](additional-responses.md){.internal-link target=_blank}。 +OpenAPIでは `responses` を使ってメディアタイプやその他の詳細を宣言することもできます: [OpenAPI の追加レスポンス](additional-responses.md)。 diff --git a/docs/ja/docs/advanced/dataclasses.md b/docs/ja/docs/advanced/dataclasses.md index 74f479f072..e3ad7afb63 100644 --- a/docs/ja/docs/advanced/dataclasses.md +++ b/docs/ja/docs/advanced/dataclasses.md @@ -2,11 +2,11 @@ FastAPI は **Pydantic** の上に構築されており、これまでにリクエストやレスポンスを宣言するために Pydantic モデルを使う方法を紹介してきました。 -しかし FastAPI は、同様の方法で `dataclasses` もサポートします: +しかし FastAPI は、同様の方法で [`dataclasses`](https://docs.python.org/3/library/dataclasses.html) もサポートします: {* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *} -これは **Pydantic** によって引き続きサポートされています。Pydantic には `dataclasses` の内部サポート があるためです。 +これは **Pydantic** によって引き続きサポートされています。Pydantic には [`dataclasses` の内部サポート](https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel) があるためです。 そのため、上記のように明示的に Pydantic を使っていないコードでも、FastAPI は標準の dataclass を Pydantic 独自の dataclass に変換するために Pydantic を使用しています。 @@ -74,7 +74,7 @@ dataclass は自動的に Pydantic の dataclass に変換されます。 いつもどおり、FastAPI では必要に応じて `def` と `async def` を組み合わせられます。 - どちらをいつ使うかの復習が必要な場合は、[`async` と `await`](../async.md#in-a-hurry){.internal-link target=_blank} に関するドキュメントの _"In a hurry?"_ セクションを参照してください。 + どちらをいつ使うかの復習が必要な場合は、[`async` と `await`](../async.md#in-a-hurry) に関するドキュメントの _"In a hurry?"_ セクションを参照してください。 9. この *path operation 関数* は（可能ではありますが）dataclass 自体は返さず、内部データを持つ辞書のリストを返しています。 @@ -88,7 +88,7 @@ dataclass は自動的に Pydantic の dataclass に変換されます。 `dataclasses` を他の Pydantic モデルと組み合わせたり、継承したり、自分のモデルに含めたりもできます。 -詳しくは、dataclasses に関する Pydantic ドキュメント を参照してください。 +詳しくは、[dataclasses に関する Pydantic ドキュメント](https://docs.pydantic.dev/latest/concepts/dataclasses/) を参照してください。 ## バージョン { #version } diff --git a/docs/ja/docs/advanced/events.md b/docs/ja/docs/advanced/events.md index fb79062fa8..e2cbe2eb04 100644 --- a/docs/ja/docs/advanced/events.md +++ b/docs/ja/docs/advanced/events.md @@ -150,11 +150,11 @@ async with lifespan(app): 技術が気になる方への細かな詳細です。🤓 -内部的には、ASGI の技術仕様において、これは Lifespan プロトコル の一部であり、`startup` と `shutdown` というイベントが定義されています。 +内部的には、ASGI の技術仕様において、これは [Lifespan プロトコル](https://asgi.readthedocs.io/en/latest/specs/lifespan.html) の一部であり、`startup` と `shutdown` というイベントが定義されています。 /// info | 情報 -Starlette の `lifespan` ハンドラについては、Starlette の Lifespan ドキュメントで詳しく読むことができます。 +Starlette の `lifespan` ハンドラについては、[Starlette の Lifespan ドキュメント](https://www.starlette.dev/lifespan/)で詳しく読むことができます。 コードの他の領域で使える lifespan の状態をどのように扱うかも含まれています。 @@ -162,4 +162,4 @@ Starlette の `lifespan` ハンドラについては、OpenAPI Generator があります。これは**多数のプログラミング言語**をサポートし、OpenAPI 仕様から SDK を生成できます。 +多用途な選択肢として [OpenAPI Generator](https://openapi-generator.tech/) があります。これは**多数のプログラミング言語**をサポートし、OpenAPI 仕様から SDK を生成できます。 -**TypeScript クライアント**向けには、Hey API が目的特化のソリューションで、TypeScript エコシステムに最適化された体験を提供します。 +**TypeScript クライアント**向けには、[Hey API](https://heyapi.dev/) が目的特化のソリューションで、TypeScript エコシステムに最適化された体験を提供します。 -他の SDK ジェネレータは OpenAPI.Tools でも見つけられます。 +他の SDK ジェネレータは [OpenAPI.Tools](https://openapi.tools/#sdk) でも見つけられます。 /// tip | 豆知識 @@ -24,15 +24,15 @@ FastAPI は自動的に **OpenAPI 3.1** の仕様を生成します。したが このセクションでは、FastAPI をスポンサーしている企業による、**ベンチャー支援**および**企業支援**のソリューションを紹介します。これらの製品は、高品質な生成 SDK に加えて、**追加機能**や**統合**を提供します。 -✨ [**FastAPI をスポンサーする**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨ ことで、これらの企業はフレームワークとその**エコシステム**の健全性と**持続可能性**を支援しています。 +✨ [**FastAPI をスポンサーする**](../help-fastapi.md#sponsor-the-author) ✨ ことで、これらの企業はフレームワークとその**エコシステム**の健全性と**持続可能性**を支援しています。 この支援は、FastAPI の**コミュニティ**（皆さん）への強いコミットメントの表明でもあり、**優れたサービス**の提供だけでなく、堅牢で発展するフレームワーク FastAPI を支える姿勢を示しています。🙇 例えば、次のようなものがあります: -* Speakeasy -* Stainless -* liblab +* [Speakeasy](https://speakeasy.com/editor?utm_source=fastapi+repo&utm_medium=github+sponsorship) +* [Stainless](https://www.stainless.com/?utm_source=fastapi&utm_medium=referral) +* [liblab](https://developers.liblab.com/tutorials/sdk-for-fastapi?utm_source=fastapi) これらのソリューションの中にはオープンソースや無料枠を提供するものもあり、金銭的コミットメントなしで試すことができます。他の商用 SDK ジェネレータも存在し、オンラインで見つけられます。🤓 @@ -66,7 +66,7 @@ npx @hey-api/openapi-ts -i http://localhost:8000/openapi.json -o src/client これで TypeScript SDK が `./src/client` に生成されます。 -`@hey-api/openapi-ts` のインストール方法や、生成物の詳細は公式サイトを参照してください。 +[`@hey-api/openapi-ts` のインストール方法](https://heyapi.dev/openapi-ts/get-started)や、[生成物の詳細](https://heyapi.dev/openapi-ts/output)は公式サイトを参照してください。 ### SDK の利用 { #using-the-sdk } diff --git a/docs/ja/docs/advanced/index.md b/docs/ja/docs/advanced/index.md index 1d0f7566cd..026405318f 100644 --- a/docs/ja/docs/advanced/index.md +++ b/docs/ja/docs/advanced/index.md @@ -2,7 +2,7 @@ ## さらなる機能 { #additional-features } -メインの[チュートリアル - ユーザーガイド](../tutorial/index.md){.internal-link target=_blank}だけで、**FastAPI**の主要な機能を一通り把握するには十分なはずです。 +メインの[チュートリアル - ユーザーガイド](../tutorial/index.md)だけで、**FastAPI**の主要な機能を一通り把握するには十分なはずです。 以降のセクションでは、その他のオプション、設定、追加機能を見ていきます。 @@ -16,6 +16,6 @@ ## 先にチュートリアルを読む { #read-the-tutorial-first } -メインの[チュートリアル - ユーザーガイド](../tutorial/index.md){.internal-link target=_blank}で得た知識があれば、**FastAPI**の機能の多くは引き続き利用できます。 +メインの[チュートリアル - ユーザーガイド](../tutorial/index.md)で得た知識があれば、**FastAPI**の機能の多くは引き続き利用できます。 また、以降のセクションでは、すでにそれを読んでいて、主要な考え方を理解していることを前提としています。 diff --git a/docs/ja/docs/advanced/middleware.md b/docs/ja/docs/advanced/middleware.md index 2883d53d82..018e660588 100644 --- a/docs/ja/docs/advanced/middleware.md +++ b/docs/ja/docs/advanced/middleware.md @@ -1,8 +1,8 @@ # 高度なミドルウェア { #advanced-middleware } -メインのチュートリアルでは、アプリケーションに[カスタムミドルウェア](../tutorial/middleware.md){.internal-link target=_blank}を追加する方法を学びました。 +メインのチュートリアルでは、アプリケーションに[カスタムミドルウェア](../tutorial/middleware.md)を追加する方法を学びました。 -そして、[`CORSMiddleware` を使った CORS の扱い方](../tutorial/cors.md){.internal-link target=_blank}も学びました。 +そして、[`CORSMiddleware` を使った CORS の扱い方](../tutorial/cors.md)も学びました。 このセクションでは、その他のミドルウェアの使い方を見ていきます。 @@ -91,7 +91,7 @@ HTTP Host Header 攻撃を防ぐため、すべての受信リクエストに正 例えば: -- Uvicorn の `ProxyHeadersMiddleware` -- MessagePack +- [Uvicorn の `ProxyHeadersMiddleware`](https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py) +- [MessagePack](https://github.com/florimondmanca/msgpack-asgi) -他に利用可能なミドルウェアについては、Starlette のミドルウェアドキュメントや ASGI Awesome List を参照してください。 +他に利用可能なミドルウェアについては、[Starlette のミドルウェアドキュメント](https://www.starlette.dev/middleware/)や [ASGI Awesome List](https://github.com/florimondmanca/awesome-asgi) を参照してください。 diff --git a/docs/ja/docs/advanced/openapi-callbacks.md b/docs/ja/docs/advanced/openapi-callbacks.md index 283a80b210..31d17e270b 100644 --- a/docs/ja/docs/advanced/openapi-callbacks.md +++ b/docs/ja/docs/advanced/openapi-callbacks.md @@ -35,7 +35,7 @@ /// tip | 豆知識 -`callback_url` クエリパラメータは、Pydantic の Url 型を使用します。 +`callback_url` クエリパラメータは、Pydantic の [Url](https://docs.pydantic.dev/latest/api/networks/) 型を使用します。 /// @@ -66,7 +66,7 @@ httpx.post(callback_url, json={"description": "Invoice paid", "paid": True}) 実際のコールバックは単なる HTTP リクエストです。 -自分でコールバックを実装する場合は、HTTPX や Requests のようなものを使えます。 +自分でコールバックを実装する場合は、[HTTPX](https://www.python-httpx.org) や [Requests](https://requests.readthedocs.io/) のようなものを使えます。 /// @@ -106,11 +106,11 @@ httpx.post(callback_url, json={"description": "Invoice paid", "paid": True}) 通常の *path operation* と異なる主な点が 2 つあります: * 実際のコードは不要です。あなたのアプリはこのコードを決して呼びません。これは *外部 API* をドキュメント化するためだけに使われます。したがって、関数本体は `pass` で構いません。 -* *パス* には、*あなたの API* に送られた元のリクエストのパラメータや一部を変数として使える OpenAPI 3 の式（後述）を含められます。 +* *パス* には、*あなたの API* に送られた元のリクエストのパラメータや一部を変数として使える [OpenAPI 3 の式](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression)（後述）を含められます。 ### コールバックのパス式 { #the-callback-path-expression } -コールバックの *パス* には、*あなたの API* に送られた元のリクエストの一部を含められる OpenAPI 3 の式を使用できます。 +コールバックの *パス* には、*あなたの API* に送られた元のリクエストの一部を含められる [OpenAPI 3 の式](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression)を使用できます。 この例では、`str` は次のとおりです: @@ -179,7 +179,7 @@ JSON ボディは次のような内容です: ### ドキュメントを確認 { #check-the-docs } -アプリを起動して http://127.0.0.1:8000/docs にアクセスします。 +アプリを起動して [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) にアクセスします。 あなたの *path operation* に「Callbacks」セクションが含まれ、*外部 API* がどうあるべきかが表示されているのが確認できます: diff --git a/docs/ja/docs/advanced/openapi-webhooks.md b/docs/ja/docs/advanced/openapi-webhooks.md index 368cfddd82..7f7a726807 100644 --- a/docs/ja/docs/advanced/openapi-webhooks.md +++ b/docs/ja/docs/advanced/openapi-webhooks.md @@ -48,7 +48,7 @@ Webhook では（`/items/` のような）*パス*を宣言しているわけで ### ドキュメントの確認 { #check-the-docs } -アプリを起動し、http://127.0.0.1:8000/docs にアクセスします。 +アプリを起動し、[http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) にアクセスします。 ドキュメントには通常の *path operations* に加えて、**webhooks** も表示されます: diff --git a/docs/ja/docs/advanced/path-operation-advanced-configuration.md b/docs/ja/docs/advanced/path-operation-advanced-configuration.md index f7e3406171..65b56dba4c 100644 --- a/docs/ja/docs/advanced/path-operation-advanced-configuration.md +++ b/docs/ja/docs/advanced/path-operation-advanced-configuration.md @@ -60,7 +60,7 @@ APIの関数名を `operationId` として利用したい場合、すべてのAP 追加のレスポンスについても、モデルやステータスコードなどとともに宣言できます。 -これについてはドキュメントに章全体があります。 [OpenAPIの追加レスポンス](additional-responses.md){.internal-link target=_blank} で読めます。 +これについてはドキュメントに章全体があります。 [OpenAPIの追加レスポンス](additional-responses.md) で読めます。 ## OpenAPI Extra { #openapi-extra } @@ -68,7 +68,7 @@ APIの関数名を `operationId` として利用したい場合、すべてのAP /// note | 技術詳細 -OpenAPI仕様では Operation Object と呼ばれています。 +OpenAPI仕様では [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object) と呼ばれています。 /// @@ -82,7 +82,7 @@ OpenAPI仕様では Starlette のドキュメントを参照してください。 +利用可能なすべてのパラメータやオプションについては、[Starlette のドキュメント](https://www.starlette.dev/responses/#set-cookie)を参照してください。 diff --git a/docs/ja/docs/advanced/response-directly.md b/docs/ja/docs/advanced/response-directly.md index 103e84c385..1c2b83c2cb 100644 --- a/docs/ja/docs/advanced/response-directly.md +++ b/docs/ja/docs/advanced/response-directly.md @@ -1,22 +1,26 @@ # レスポンスを直接返す { #return-a-response-directly } -**FastAPI** の *path operation* では、通常は任意のデータを返すことができます: 例えば、 `dict`、`list`、Pydanticモデル、データベースモデルなどです。 +**FastAPI** の *path operation* では、通常は任意のデータを返すことができます: 例えば、`dict`、`list`、Pydanticモデル、データベースモデルなどです。 -デフォルトでは、**FastAPI** は [JSON互換エンコーダ](../tutorial/encoder.md){.internal-link target=_blank} で説明されている `jsonable_encoder` により、返す値を自動的にJSONに変換します。 +[レスポンスモデル](../tutorial/response-model.md) を宣言した場合、FastAPI は Pydantic を使ってデータをJSONにシリアライズします。 -このとき背後では、JSON互換なデータ (例えば`dict`) を、クライアントへ送信されるレスポンスとして利用される `JSONResponse` の中に含めます。 +レスポンスモデルを宣言しない場合、FastAPI は [JSON互換エンコーダ](../tutorial/encoder.md){.internal-link target=_blank} で説明されている `jsonable_encoder` を使用し、その結果を `JSONResponse` に入れます。 -しかし、*path operation* から `JSONResponse` を直接返すこともできます。 +また、`JSONResponse` を直接作成して返すこともできます。 -これは例えば、カスタムヘッダーやcookieを返すときに便利です。 +/// tip + +通常は、`JSONResponse` を直接返すよりも、[レスポンスモデル](../tutorial/response-model.md) を使うほうがパフォーマンスが大幅に良くなります。これは、Pydantic によるシリアライズが Rust で実行されるためです。 + +/// ## `Response` を返す { #return-a-response } 実際は、`Response` やそのサブクラスを返すことができます。 -/// tip | 豆知識 +/// info -`JSONResponse` それ自体は、 `Response` のサブクラスです。 +`JSONResponse` それ自体は、`Response` のサブクラスです。 /// @@ -26,6 +30,8 @@ これは多くの柔軟性を提供します。任意のデータ型を返したり、任意のデータ宣言やバリデーションをオーバーライドできます。 +同時に多くの責任も伴います。返すデータが正しく、正しいフォーマットであり、シリアライズ可能であることなどを、あなたが保証しなければなりません。 + ## `jsonable_encoder` を `Response` の中で使う { #using-the-jsonable-encoder-in-a-response } **FastAPI** はあなたが返す `Response` に対して何も変更を加えないので、コンテンツが準備できていることを保証しなければなりません。 @@ -46,16 +52,28 @@ ## カスタム `Response` を返す { #returning-a-custom-response } -上記の例では必要な部分を全て示していますが、あまり便利ではありません。`item` を直接返すことができるし、**FastAPI** はそれを `dict` に変換して `JSONResponse`　に含めてくれるなど。すべて、デフォルトの動作です。 +上記の例では必要な部分を全て示していますが、あまり便利ではありません。`item` を直接返すことができるし、**FastAPI** はそれを `dict` に変換して `JSONResponse` に含めてくれるなど。すべて、デフォルトの動作です。 では、これを使ってカスタムレスポンスをどう返すか見てみましょう。 -XMLレスポンスを返したいとしましょう。 +[XML](https://en.wikipedia.org/wiki/XML)レスポンスを返したいとしましょう。 XMLを文字列にし、`Response` に含め、それを返します。 {* ../../docs_src/response_directly/tutorial002_py310.py hl[1,18] *} +## Response Model の仕組み { #how-a-response-model-works } + +path operation で [Response Model - 戻り値の型](../tutorial/response-model.md) を宣言すると、**FastAPI** はそれを使って Pydantic によりデータをJSONにシリアライズします。 + +{* ../../docs_src/response_model/tutorial001_01_py310.py hl[16,21] *} + +これは Rust 側で行われるため、通常の Python と `JSONResponse` クラスで行う場合より、パフォーマンスははるかに良くなります。 + +`response_model` や戻り値の型を使用する場合、FastAPI はデータ変換に（低速になりうる）`jsonable_encoder` も `JSONResponse` クラスも使いません。 + +代わりに、response model（または戻り値の型）を使って Pydantic が生成した JSON のバイト列をそのまま用い、JSON 用の正しいメディアタイプ（`application/json`）を持つ `Response` を直接返します。 + ## 備考 { #notes } `Response` を直接返す場合、バリデーションや、変換 (シリアライズ) や、自動ドキュメントは行われません。 diff --git a/docs/ja/docs/advanced/response-headers.md b/docs/ja/docs/advanced/response-headers.md index 10aec78452..3a61f57428 100644 --- a/docs/ja/docs/advanced/response-headers.md +++ b/docs/ja/docs/advanced/response-headers.md @@ -20,7 +20,7 @@ `Response` を直接返す場合にもヘッダーを追加できます。 -[Response を直接返す](response-directly.md){.internal-link target=_blank} で説明したようにレスポンスを作成し、ヘッダーを追加のパラメータとして渡します: +[Response を直接返す](response-directly.md) で説明したようにレスポンスを作成し、ヘッダーを追加のパラメータとして渡します: {* ../../docs_src/response_headers/tutorial001_py310.py hl[10:12] *} @@ -36,6 +36,6 @@ ## カスタムヘッダー { #custom-headers } -独自のカスタムヘッダーは、`X-` プレフィックスを使って追加できることに注意してください。 +独自のカスタムヘッダーは、[`X-` プレフィックスを使って](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)追加できることに注意してください。 -ただし、ブラウザのクライアントに見えるようにしたいカスタムヘッダーがある場合は、CORS 設定にそれらを追加する必要があります（[CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md){.internal-link target=_blank} を参照）。このとき、Starlette の CORS ドキュメントに記載の `expose_headers` パラメータを使用します。 +ただし、ブラウザのクライアントに見えるようにしたいカスタムヘッダーがある場合は、CORS 設定にそれらを追加する必要があります（[CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md) を参照）。このとき、[Starlette の CORS ドキュメント](https://www.starlette.dev/middleware/#corsmiddleware)に記載の `expose_headers` パラメータを使用します。 diff --git a/docs/ja/docs/advanced/security/http-basic-auth.md b/docs/ja/docs/advanced/security/http-basic-auth.md index 7ee56a039b..b8e47dcbb7 100644 --- a/docs/ja/docs/advanced/security/http-basic-auth.md +++ b/docs/ja/docs/advanced/security/http-basic-auth.md @@ -32,7 +32,7 @@ URL を最初に開こうとしたとき（またはドキュメントで「Exec 依存関係を使ってユーザー名とパスワードが正しいかを確認します。 -これには、Python 標準モジュール `secrets` を用いてユーザー名とパスワードを検証します。 +これには、Python 標準モジュール [`secrets`](https://docs.python.org/3/library/secrets.html) を用いてユーザー名とパスワードを検証します。 `secrets.compare_digest()` は `bytes` か、ASCII 文字（英語の文字）のみを含む `str` を受け取る必要があります。つまり、`Sebastián` のように `á` を含む文字ではそのままでは動作しません。 @@ -46,7 +46,7 @@ URL を最初に開こうとしたとき（またはドキュメントで「Exec ```Python if not (credentials.username == "stanleyjobson") or not (credentials.password == "swordfish"): - # Return some error + # 何らかのエラーを返す ... ``` diff --git a/docs/ja/docs/advanced/security/index.md b/docs/ja/docs/advanced/security/index.md index 069e2686cb..f1f9eee046 100644 --- a/docs/ja/docs/advanced/security/index.md +++ b/docs/ja/docs/advanced/security/index.md @@ -6,7 +6,7 @@ /// tip | 豆知識 -次の節は必ずしも「高度」ではありません。 +次の節は**必ずしも「高度」ではありません**。 あなたのユースケースでは、その中のいずれかに解決策があるかもしれません。 diff --git a/docs/ja/docs/advanced/settings.md b/docs/ja/docs/advanced/settings.md index 5508ad6d91..e42ec845c6 100644 --- a/docs/ja/docs/advanced/settings.md +++ b/docs/ja/docs/advanced/settings.md @@ -8,7 +8,7 @@ /// tip | 豆知識 -環境変数について理解するには、[環境変数](../environment-variables.md){.internal-link target=_blank}を参照してください。 +環境変数について理解するには、[環境変数](../environment-variables.md)を参照してください。 /// @@ -20,11 +20,11 @@ ## Pydantic の `Settings` { #pydantic-settings } -幸いなことに、Pydantic には環境変数から来る設定を扱うための優れたユーティリティがあり、Pydantic: Settings management で提供されています。 +幸いなことに、Pydantic には環境変数から来る設定を扱うための優れたユーティリティがあり、[Pydantic: Settings management](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) で提供されています。 ### `pydantic-settings` のインストール { #install-pydantic-settings } -まず、[仮想環境](../virtual-environments.md){.internal-link target=_blank}を作成して有効化し、`pydantic-settings` パッケージをインストールします: +まず、[仮想環境](../virtual-environments.md)を作成して有効化し、`pydantic-settings` パッケージをインストールします:
@@ -100,7 +100,7 @@ $ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.p ## 別モジュールでの設定 { #settings-in-another-module } -[大規模アプリケーション - 複数ファイル](../tutorial/bigger-applications.md){.internal-link target=_blank} で見たように、これらの設定を別のモジュールファイルに置くこともできます。 +[大規模アプリケーション - 複数ファイル](../tutorial/bigger-applications.md) で見たように、これらの設定を別のモジュールファイルに置くこともできます。 たとえば、`config.py` というファイルに次のように書けます: @@ -112,7 +112,7 @@ $ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.p /// tip | 豆知識 -[大規模アプリケーション - 複数ファイル](../tutorial/bigger-applications.md){.internal-link target=_blank} で見たように、`__init__.py` ファイルも必要です。 +[大規模アプリケーション - 複数ファイル](../tutorial/bigger-applications.md) で見たように、`__init__.py` ファイルも必要です。 /// @@ -172,7 +172,7 @@ $ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.p /// -Pydantic は外部ライブラリを使ってこの種のファイルからの読み込みをサポートしています。詳細は Pydantic Settings: Dotenv (.env) support を参照してください。 +Pydantic は外部ライブラリを使ってこの種のファイルからの読み込みをサポートしています。詳細は [Pydantic Settings: Dotenv (.env) support](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support) を参照してください。 /// tip | 豆知識 @@ -197,7 +197,7 @@ APP_NAME="ChimichangApp" /// tip | 豆知識 -`model_config` 属性は Pydantic の設定専用です。詳しくは Pydantic: Concepts: Configuration を参照してください。 +`model_config` 属性は Pydantic の設定専用です。詳しくは [Pydantic: Concepts: Configuration](https://docs.pydantic.dev/latest/concepts/config/) を参照してください。 /// @@ -291,7 +291,7 @@ participant execute as Execute function この方法は、ほとんどグローバル変数のように振る舞います。しかし、依存関数を使っているので、テストのために簡単にオーバーライドできます。 -`@lru_cache` は Python 標準ライブラリの `functools` の一部です。詳細は Python の `@lru_cache` ドキュメントを参照してください。 +`@lru_cache` は Python 標準ライブラリの `functools` の一部です。詳細は [Python の `@lru_cache` ドキュメント](https://docs.python.org/3/library/functools.html#functools.lru_cache)を参照してください。 ## まとめ { #recap } diff --git a/docs/ja/docs/advanced/sub-applications.md b/docs/ja/docs/advanced/sub-applications.md index f38da1423e..e9b17031b5 100644 --- a/docs/ja/docs/advanced/sub-applications.md +++ b/docs/ja/docs/advanced/sub-applications.md @@ -30,25 +30,25 @@ ### 自動 API ドキュメントの確認 { #check-the-automatic-api-docs } -では、`fastapi` コマンドでこのファイルを実行します: +では、`fastapi` コマンドを実行します:
```console -$ fastapi dev main.py +$ fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
-そして、http://127.0.0.1:8000/docs を開きます。 +そして、[http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) を開きます。 メインアプリ用の自動 API ドキュメントが表示され、そのアプリ自身の path operation のみが含まれます: -次に、サブアプリケーションのドキュメント http://127.0.0.1:8000/subapi/docs を開きます。 +次に、サブアプリケーションのドキュメント [http://127.0.0.1:8000/subapi/docs](http://127.0.0.1:8000/subapi/docs) を開きます。 サブアプリケーション用の自動 API ドキュメントが表示され、そのアプリ自身の path operation のみが、正しいサブパス接頭辞 `/subapi` の下で表示されます: @@ -64,4 +64,4 @@ $ fastapi dev main.py さらに、サブアプリケーション自身が別のサブアプリケーションをマウントしていても問題ありません。FastAPI がこれらの `root_path` をすべて自動的に処理するためです。 -`root_path` の詳細や明示的な指定方法については、[プロキシの背後で](behind-a-proxy.md){.internal-link target=_blank} の節で学べます。 +`root_path` の詳細や明示的な指定方法については、[プロキシの背後で](behind-a-proxy.md) の節で学べます。 diff --git a/docs/ja/docs/advanced/templates.md b/docs/ja/docs/advanced/templates.md index 3c4827b88e..5495b73a0b 100644 --- a/docs/ja/docs/advanced/templates.md +++ b/docs/ja/docs/advanced/templates.md @@ -8,7 +8,7 @@ Starlette によって提供され、**FastAPI** アプリで直接使える、 ## 依存関係のインストール { #install-dependencies } -[仮想環境](../virtual-environments.md){.internal-link target=_blank} を作成して有効化し、`jinja2` をインストールします: +[仮想環境](../virtual-environments.md) を作成して有効化し、`jinja2` をインストールします:
@@ -123,4 +123,4 @@ Item ID: 42 ## さらに詳しく { #more-details } -より詳しい内容（テンプレートのテスト方法など）については、Starlette のテンプレートに関するドキュメントを参照してください。 +より詳しい内容（テンプレートのテスト方法など）については、[Starlette のテンプレートに関するドキュメント](https://www.starlette.dev/templates/)を参照してください。 diff --git a/docs/ja/docs/advanced/testing-websockets.md b/docs/ja/docs/advanced/testing-websockets.md index 7f708ea1a2..745e636087 100644 --- a/docs/ja/docs/advanced/testing-websockets.md +++ b/docs/ja/docs/advanced/testing-websockets.md @@ -8,6 +8,6 @@ WebSocket をテストするのにも同じ `TestClient` を使用できます /// note | 備考 -詳細については、Starlette のドキュメント「WebSocket のテスト」を参照してください。 +詳細については、Starlette のドキュメント「[WebSocket のテスト](https://www.starlette.dev/testclient/#testing-websocket-sessions)」を参照してください。 /// diff --git a/docs/ja/docs/advanced/using-request-directly.md b/docs/ja/docs/advanced/using-request-directly.md index 1e564f5945..59d7290e67 100644 --- a/docs/ja/docs/advanced/using-request-directly.md +++ b/docs/ja/docs/advanced/using-request-directly.md @@ -15,7 +15,7 @@ ## `Request` オブジェクトの詳細 { #details-about-the-request-object } -**FastAPI** は内部的には **Starlette** の上にいくつかのツール層を載せたものなので、必要に応じて Starlette の `Request` オブジェクトを直接使えます。 +**FastAPI** は内部的には **Starlette** の上にいくつかのツール層を載せたものなので、必要に応じて Starlette の [`Request`](https://www.starlette.dev/requests/) オブジェクトを直接使えます。 また、`Request` オブジェクトから直接データ（例: ボディ）を取得する場合、そのデータは FastAPI によって検証・変換・ドキュメント化（OpenAPI による自動 API ユーザーインターフェース向け）されません。 @@ -45,7 +45,7 @@ path operation 関数の引数として `Request` 型のパラメータを宣言 ## `Request` のドキュメント { #request-documentation } -より詳しくは、公式 Starlette ドキュメントサイトの `Request` オブジェクトを参照してください。 +より詳しくは、[公式 Starlette ドキュメントサイトの `Request` オブジェクト](https://www.starlette.dev/requests/)を参照してください。 /// note | 技術詳細 diff --git a/docs/ja/docs/advanced/websockets.md b/docs/ja/docs/advanced/websockets.md index efc02079bb..802110b587 100644 --- a/docs/ja/docs/advanced/websockets.md +++ b/docs/ja/docs/advanced/websockets.md @@ -1,10 +1,10 @@ # WebSockets { #websockets } -**FastAPI**でWebSocketsが使用できます。 +**FastAPI**で[WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)が使用できます。 ## `websockets`のインストール { #install-websockets } -[仮想環境](../virtual-environments.md){.internal-link target=_blank}を作成し、それを有効化してから、「WebSocket」プロトコルを簡単に使えるようにするPythonライブラリの`websockets`をインストールしてください。 +[仮想環境](../virtual-environments.md)を作成し、それを有効化してから、「WebSocket」プロトコルを簡単に使えるようにするPythonライブラリの`websockets`をインストールしてください。
@@ -64,19 +64,19 @@ WebSocketルートでは、メッセージを待機して送信するために ` ## 試してみる { #try-it } -ファイル名が `main.py` である場合、以下でアプリケーションを実行します。 +コードを `main.py` に入れて、アプリケーションを実行します。
```console -$ fastapi dev main.py +$ fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
-ブラウザで http://127.0.0.1:8000 を開きます。 +ブラウザで [http://127.0.0.1:8000](http://127.0.0.1:8000) を開きます。 次のようなシンプルなページが表示されます。 @@ -115,25 +115,25 @@ WebSocketエンドポイントでは、`fastapi` から以下をインポート これはWebSocketであるため、`HTTPException` を発生させることはあまり意味がありません。代わりに `WebSocketException` を発生させます。 -クロージングコードは、仕様で定義された有効なコードの中から使用することができます。 +クロージングコードは、[仕様で定義された有効なコード](https://tools.ietf.org/html/rfc6455#section-7.4.1)の中から使用することができます。 /// ### 依存関係を用いてWebSocketsを試してみる { #try-the-websockets-with-dependencies } -ファイル名が `main.py` である場合、以下でアプリケーションを実行します。 +アプリケーションを実行します。
```console -$ fastapi dev main.py +$ fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
-ブラウザで http://127.0.0.1:8000 を開きます。 +ブラウザで [http://127.0.0.1:8000](http://127.0.0.1:8000) を開きます。 そこで、以下を設定できます。 @@ -174,7 +174,7 @@ Client #1596980209979 left the chat しかし、すべてがメモリ内の単一のリストで処理されるため、プロセスの実行中にのみ機能し、単一のプロセスでのみ機能することに注意してください。 -FastAPIと簡単に統合できて、RedisやPostgreSQLなどでサポートされている、より堅牢なものが必要なら、encode/broadcaster を確認してください。 +FastAPIと簡単に統合できて、RedisやPostgreSQLなどでサポートされている、より堅牢なものが必要なら、[encode/broadcaster](https://github.com/encode/broadcaster) を確認してください。 /// @@ -182,5 +182,5 @@ FastAPIと簡単に統合できて、RedisやPostgreSQLなどでサポートさ オプションの詳細については、Starletteのドキュメントを確認してください。 -* `WebSocket` クラス. -* クラスベースのWebSocket処理. +* [`WebSocket` クラス](https://www.starlette.dev/websockets/)。 +* [クラスベースのWebSocket処理](https://www.starlette.dev/endpoints/#websocketendpoint)。 diff --git a/docs/ja/docs/advanced/wsgi.md b/docs/ja/docs/advanced/wsgi.md index b06b4a3299..6895eb6584 100644 --- a/docs/ja/docs/advanced/wsgi.md +++ b/docs/ja/docs/advanced/wsgi.md @@ -1,6 +1,6 @@ # WSGI の組み込み - Flask、Django など { #including-wsgi-flask-django-others } -[サブアプリケーション - マウント](sub-applications.md){.internal-link target=_blank}、[プロキシの背後](behind-a-proxy.md){.internal-link target=_blank} で見たように、WSGI アプリケーションをマウントできます。 +[サブアプリケーション - マウント](sub-applications.md)、[プロキシの背後](behind-a-proxy.md) で見たように、WSGI アプリケーションをマウントできます。 そのために `WSGIMiddleware` を使用して、Flask や Django などの WSGI アプリをラップできます。 @@ -36,13 +36,13 @@ それ以外は **FastAPI** が処理します。 -実行して http://localhost:8000/v1/ にアクセスすると、Flask からのレスポンスが表示されます: +実行して [http://localhost:8000/v1/](http://localhost:8000/v1/) にアクセスすると、Flask からのレスポンスが表示されます: ```txt Hello, World from Flask! ``` -さらに http://localhost:8000/v2 にアクセスすると、FastAPI からのレスポンスが表示されます: +さらに [http://localhost:8000/v2](http://localhost:8000/v2) にアクセスすると、FastAPI からのレスポンスが表示されます: ```JSON { diff --git a/docs/ja/docs/how-to/custom-request-and-route.md b/docs/ja/docs/how-to/custom-request-and-route.md index ae64f31097..23398a19cd 100644 --- a/docs/ja/docs/how-to/custom-request-and-route.md +++ b/docs/ja/docs/how-to/custom-request-and-route.md @@ -18,7 +18,7 @@ FastAPI を始めたばかりの場合は、このセクションは読み飛ば ユースケースの例: -* JSON ではないリクエストボディを JSON に変換する（例: `msgpack`）。 +* JSON ではないリクエストボディを JSON に変換する（例: [`msgpack`](https://msgpack.org/index.html)）。 * gzip 圧縮されたリクエストボディの解凍。 * すべてのリクエストボディの自動ロギング。 @@ -66,7 +66,7 @@ gzip のリクエストを解凍するために、カスタムの `Request` サ そしてこの 2 つ（`scope` と `receive`）が、新しい `Request` インスタンスを作成するために必要なものです。 -`Request` について詳しくは、Starlette の Requests に関するドキュメント を参照してください。 +`Request` について詳しくは、[Starlette の Requests に関するドキュメント](https://www.starlette.dev/requests/) を参照してください。 ///