🌐 Add Japanese translation for Tutorial - Body (#1683)

Co-authored-by: ryusuke.miyaji <[email protected]>
Co-authored-by: ryuckel <[email protected]>
Co-authored-by: Sebastián Ramírez <[email protected]>

docs/ja/docs/tutorial/body.md

@@ -0,0 +1,165 @@
+# リクエストボディ
+
+クライアント (ブラウザなど) からAPIにデータを送信する必要があるとき、データを **リクエストボディ (request body)** として送ります。
+
+**リクエスト** ボディはクライアントによってAPIへ送られます。**レスポンス** ボディはAPIがクライアントに送るデータです。
+
+APIはほとんどの場合 **レスポンス** ボディを送らなければなりません。しかし、クライアントは必ずしも **リクエスト** ボディを送らなければいけないわけではありません。
+
+**リクエスト** ボディを宣言するために <a href="https://pydantic-docs.helpmanual.io/" class="external-link" target="_blank">Pydantic</a> モデルを使用します。そして、その全てのパワーとメリットを利用します。
+
+!!! info "情報"
+    データを送るには、`POST` (もっともよく使われる)、`PUT`、`DELETE` または `PATCH` を使うべきです。
+
+    GET リクエストでボディを送信することは、仕様では未定義の動作ですが、FastAPI でサポートされており、非常に複雑な（極端な）ユースケースにのみ対応しています。
+
+    非推奨なので、Swagger UIを使った対話型のドキュメントにはGETのボディ情報は表示されません。さらに、中継するプロキシが対応していない可能性があります。
+
+## Pydanticの `BaseModel` をインポート
+
+ます初めに、 `pydantic` から `BaseModel` をインポートする必要があります:
+
+```Python hl_lines="2"
+{!../../../docs_src/body/tutorial001.py!}
+```
+
+## データモデルの作成
+
+そして、`BaseModel` を継承したクラスとしてデータモデルを宣言します。
+
+すべての属性にpython標準の型を使用します:
+
+```Python hl_lines="5-9"
+{!../../../docs_src/body/tutorial001.py!}
+```
+
+クエリパラメータの宣言と同様に、モデル属性がデフォルト値をもつとき、必須な属性ではなくなります。それ以外は必須になります。オプショナルな属性にしたい場合は `None` を使用してください。
+
+例えば、上記のモデルは以下の様なJSON「`オブジェクト`」(もしくはPythonの `dict` ) を宣言しています:
+
+```JSON
+{
+    "name": "Foo",
+    "description": "An optional description",
+    "price": 45.2,
+    "tax": 3.5
+}
+```
+
+...`description` と `tax` はオプショナル (デフォルト値は `None`) なので、以下のJSON「`オブジェクト`」も有効です:
+
+```JSON
+{
+    "name": "Foo",
+    "price": 45.2
+}
+```
+
+## パラメータとして宣言
+
+*パスオペレーション* に加えるために、パスパラメータやクエリパラメータと同じ様に宣言します:
+
+```Python hl_lines="16"
+{!../../../docs_src/body/tutorial001.py!}
+```
+
+...そして、作成したモデル `Item` で型を宣言します。
+
+## 結果
+
+そのPythonの型宣言だけで **FastAPI** は以下のことを行います:
+
+* リクエストボディをJSONとして読み取ります。
+* 適当な型に変換します（必要な場合）。
+* データを検証します。
+    * データが無効な場合は、明確なエラーが返され、どこが不正なデータであったかを示します。
+* 受け取ったデータをパラメータ `item` に変換します。
+    * 関数内で `Item` 型であると宣言したので、すべての属性とその型に対するエディタサポート（補完など）をすべて使用できます。
+* モデルの<a href="http://json-schema.org" class="external-link" target="_blank">JSONスキーマ</a>定義を生成し、好きな場所で使用することができます。
+* これらのスキーマは、生成されたOpenAPIスキーマの一部となり、自動ドキュメントの<abbr title = "User Interfaces">UI</abbr>に使用されます。
+
+## 自動ドキュメント生成
+
+モデルのJSONスキーマはOpenAPIで生成されたスキーマの一部になり、対話的なAPIドキュメントに表示されます:
+
+<img src="/img/tutorial/body/image01.png">
+
+そして、それらが使われる *パスオペレーション* のそれぞれのAPIドキュメントにも表示されます:
+
+<img src="/img/tutorial/body/image02.png">
+
+## エディターサポート
+
+エディターによる型ヒントと補完が関数内で利用できます (Pydanticモデルではなく `dict` を受け取ると、同じサポートは受けられません):
+
+<img src="/img/tutorial/body/image03.png">
+
+型によるエラーチェックも可能です:
+
+<img src="/img/tutorial/body/image04.png">
+
+これは偶然ではなく、このデザインに基づいてフレームワークが作られています。
+
+全てのエディターで機能することを確認するために、実装前の設計時に徹底的にテストしました。
+
+これをサポートするためにPydantic自体にもいくつかの変更がありました。
+
+上記のスクリーンショットは<a href="https://code.visualstudio.com" class="external-link" target="_blank">Visual Studio Code</a>を撮ったものです。
+
+しかし、<a href="https://www.jetbrains.com/pycharm/" class="external-link" target="_blank">PyCharm</a>やほとんどのPythonエディタでも同様なエディターサポートを受けられます:
+
+<img src="/img/tutorial/body/image05.png">
+
+!!! tip "豆知識"
+    <a href="https://www.jetbrains.com/pycharm/" class="external-link" target="_blank">PyCharm</a>エディタを使用している場合は、<a href="https://github.com/koxudaxi/pydantic-pycharm-plugin/" class="external-link" target="_blank">Pydantic PyCharm Plugin</a>が使用可能です。
+
+    以下のエディターサポートが強化されます:
+    
+    * 自動補完
+    * 型チェック
+    * リファクタリング
+    * 検索
+    * インスペクション
+
+## モデルの使用
+
+関数内部で、モデルの全ての属性に直接アクセスできます:
+
+```Python hl_lines="19"
+{!../../../docs_src/body/tutorial002.py!}
+```
+
+## リクエストボディ + パスパラメータ
+
+パスパラメータとリクエストボディを同時に宣言できます。
+
+**FastAPI** はパスパラメータである関数パラメータは**パスから受け取り**、Pydanticモデルによって宣言された関数パラメータは**リクエストボディから受け取る**ということを認識します。
+
+```Python hl_lines="15-16"
+{!../../../docs_src/body/tutorial003.py!}
+```
+
+## リクエストボディ + パスパラメータ + クエリパラメータ
+
+また、**ボディ**と**パス**と**クエリ**のパラメータも同時に宣言できます。
+
+**FastAPI** はそれぞれを認識し、適切な場所からデータを取得します。
+
+```Python hl_lines="16"
+{!../../../docs_src/body/tutorial004.py!}
+```
+
+関数パラメータは以下の様に認識されます:
+
+* パラメータが**パス**で宣言されている場合は、優先的にパスパラメータとして扱われます。
+* パラメータが**単数型** (`int`、`float`、`str`、`bool` など)の場合は**クエリ**パラメータとして解釈されます。
+* パラメータが **Pydantic モデル**型で宣言された場合、リクエスト**ボディ**として解釈されます。
+
+!!! note "備考"
+    FastAPIは、`= None`があるおかげで、`q`がオプショナルだとわかります。
+ 
+    `Optional[str]` の`Optional` はFastAPIでは使用されていません（FastAPIは`str`の部分のみ使用します）。しかし、`Optional[str]` はエディタがコードのエラーを見つけるのを助けてくれます。
+
+## Pydanticを使わない方法
+
+もしPydanticモデルを使用したくない場合は、**ボディ**パラメータが利用できます。[Body - Multiple Parameters: Singular values in body](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}を確認してください。

docs/ja/mkdocs.yml

@@ -42,6 +42,7 @@ nav:
   - tutorial/first-steps.md
   - tutorial/path-params.md
   - tutorial/query-params.md
+  - tutorial/body.md
 markdown_extensions:
 - toc:
     permalink: true