docs(ja): update Japanese docs (08/17/2024 ~ 09/21/2024) (#1924)

yoshi2no · web-flow · commit 08b537b947b8 · 2024-10-25T09:52:42.000-06:00
* docs(ja): add `--root-types` to cli flags, a9cd9aa * docs(ja): add `web-bee-ru/openapi-axios` to examples, 4fc9588 * docs(ja): add tip on openapi-fetch Content-Type, b893c44 * docs(ja): add `baseUrl` to fetch options, 2a4b067 * docs(ja): fix a few expressions
diff --git a/docs/ja/cli.md b/docs/ja/cli.md
@@ -119,6 +119,7 @@ CLI は以下のフラグをサポートしています：
 | `--export-type`                    | `-t`       |  `false`   | `interface` の代わりに `type` をエクスポートします                                                       |
 | `--immutable`                      |            |  `false`   | 不変の型（readonlyプロパティおよびreadonly配列）を生成します                                             |
 | `--path-params-as-types`           |            |  `false`   | `paths` オブジェクトで動的な文字列の参照を許可します                                                     |
+| `--root-types`                     |            |  `false`   | `components` から型をルートレベルの型エイリアスとしてエクスポートする                                        |
 
 ### pathParamsAsTypes
 
diff --git a/docs/ja/examples.md b/docs/ja/examples.md
@@ -142,6 +142,82 @@ try {
 
 </details>
 
+<details>
+<summary><a href="https://www.npmjs.com/package/@web-bee-ru/openapi-axios" target="_blank" rel="noreferrer">openapi-axios</a> by <a href="https://github.com/web-bee-ru" target="_blank" rel="noreferrer">@web-bee-ru</a></summary>
+
+::: code-group
+
+```ts [test/my-project.ts]
+import { OpenApiAxios } from "@web-bee-ru/openapi-axios";
+import type { paths } from "./my-openapi-3-schema"; // openapi-typescriptで生成された型
+import Axios from "axios";
+
+const axios = Axios.create({
+  baseURL: "https://myapi.dev/v1",
+  adapter: "fetch", // 強く推奨 (axios@1.7.0 から利用可能)
+});
+
+// 例1. "axios"（デフォルト）のステータス処理方法での使用 (validStatus: 'axios')
+
+// axiosのようにエラーをスローする（例：status >= 400、ネットワークエラー、インターセプターエラー）
+const api = new OpenApiAxios<paths, "axios">(axios, { validStatus: "axios" });
+
+// const api =  new OpenApiAxios<paths>(axios) // 同じ結果になる
+
+try {
+  const { status, data, response } = await api.get("/users");
+} catch (err) {
+  if (api.isAxiosError(err)) {
+    if (typeof err.status === "number") {
+      // status >= 400
+    }
+    // リクエスト失敗（例：ネットワークエラー）
+  }
+  throw err; // axios.interceptors のエラー
+}
+
+// 例2. "fetch" ステータス処理方法での使用 (validStatus: 'fetch')
+
+// ブラウザのfetch()のようにエラーをスローする（例：ネットワークエラー、インターセプターエラー）
+const fetchApi = new OpenApiAxios<paths, "fetch">(axios, {
+  validStatus: "fetch",
+});
+
+try {
+  const { status, data, error, response } = await api.get("/users");
+
+  if (error) {
+    // status >= 400
+  }
+} catch (err) {
+  if (api.isAxiosError(err)) {
+    // リクエスト失敗（例：ネットワークエラー）
+  }
+  throw err; // axios.interceptors のエラー
+}
+
+// 例3. "safe" ステータス処理方法での使用 (validStatus: 'all')
+// （try/catch は不要）
+
+// エラーは投げない
+const safeApi = new OpenApiAxios<paths, "all">(axios, { validStatus: "all" });
+
+const { status, data, error, response } = await api.get("/users");
+
+if (error) {
+  if (typeof status === "number") {
+    // status >= 400
+  } else if (api.isAxiosError(error)) {
+    // リクエスト失敗（例：ネットワークエラー)
+  }
+  throw error; // axios.interceptors のエラー
+}
+```
+
+:::
+
+</details>
+
 ::: tip
 
 良い fetch ラッパーは**ジェネリクスの使用は避ける**べきです。ジェネリクスは多くのタイプ指定が必要で、エラーを隠してしまう可能性があります！
diff --git a/docs/ja/openapi-fetch/api.md b/docs/ja/openapi-fetch/api.md
@@ -36,6 +36,7 @@ client.GET("/my-url", options);
 | `querySerializer` | QuerySerializer                                                   | (任意) [querySerializer](#queryserializer) を提供します                                                                                                                                                                                    |
 | `bodySerializer`  | BodySerializer                                                    | (任意) [bodySerializer](#bodyserializer) を提供します                                                                                                                                                                                      |
 | `parseAs`         | `"json"` \| `"text"` \| `"arrayBuffer"` \| `"blob"` \| `"stream"` | (任意) [組み込みのインスタンスメソッド](https://developer.mozilla.org/en-US/docs/Web/API/Response#instance_methods) を使用してレスポンスを解析します (デフォルト: `"json"`). `"stream"` は解析をスキップし、未処理のストリームを返します。 |
+| `baseUrl`         | `string`                                                          | fetch URL にこのオプションで指定されたプレフィックスを付与します (e.g. `"https://myapi.dev/v1/"`)                                                                                                                                          |
 | `fetch`           | `fetch`                                                           | リクエストに使用する Fetch インスタンス (デフォルト: `createClient` で指定された fetch )                                                                                                                                                   |
 | `middleware`      | `Middleware[]`                                                    | [ドキュメントを参照](/openapi-fetch/middleware-auth)                                                                                                                                                                                       |
 | (Fetch options)   |                                                                   | 有効なすべての fetch オプション(`headers`, `mode`, `cache`, `signal`など) ([ドキュメント](https://developer.mozilla.org/en-US/docs/Web/API/fetch#options))                                                                                 |
@@ -180,6 +181,15 @@ const { data, error } = await client.PUT("/submit", {
 });
 ```
 
+::: tip
+
+便宜上、`openapi-fetch` は `body` パラメーターに値が指定されたリクエストに対して、`Content-Type` を `application/json` に自動で設定します。
+`bodySerializer` が `FormData` のインスタンスを返す場合、`Content-Type` ヘッダーは省略され、ブラウザがメッセージの複数のパートを正しく区切るboundaryを含む `Content-Type` を自動的に設定します。
+
+また、fetch オプションやクライアントのインスタンス化時に、`headers` オブジェクトを通じて `Content-Type` を手動で設定することもできます。
+
+:::
+
 ## Pathのシリアライズ
 
 openapi-fetchは、[3.1仕様書に記載されている](https://swagger.io/docs/specification/serialization/#path)ように、pathのシリアライズをサポートしています。これは、OpenAPIスキーマ内の特定のフォーマットに基づいて自動的に行われます。
diff --git a/docs/openapi-fetch/api.md b/docs/openapi-fetch/api.md
@@ -36,7 +36,7 @@ client.GET("/my-url", options);
 | `querySerializer` | QuerySerializer                                                   | (optional) Provide a [querySerializer](#queryserializer)                                                                                                                                                                          |
 | `bodySerializer`  | BodySerializer                                                    | (optional) Provide a [bodySerializer](#bodyserializer)                                                                                                                                                                            |
 | `parseAs`         | `"json"` \| `"text"` \| `"arrayBuffer"` \| `"blob"` \| `"stream"` | (optional) Parse the response using [a built-in instance method](https://developer.mozilla.org/en-US/docs/Web/API/Response#instance_methods) (default: `"json"`). `"stream"` skips parsing altogether and returns the raw stream. |
-| `baseUrl`         | `string`                                                          | Prefix the fetch URL with this option (e.g. "https://myapi.dev/v1/")                                                                                                                                                              |
+| `baseUrl`         | `string`                                                          | Prefix the fetch URL with this option (e.g. `"https://myapi.dev/v1/"`)                                                                                                                                                              |
 | `fetch`           | `fetch`                                                           | Fetch instance used for requests (default: fetch from `createClient`)                                                                                                                                                             |
 | `middleware`      | `Middleware[]`                                                    | [See docs](/openapi-fetch/middleware-auth)                                                                                                                                                                                        |
 | (Fetch options)   |                                                                   | Any valid fetch option (`headers`, `mode`, `cache`, `signal`, …) ([docs](https://developer.mozilla.org/en-US/docs/Web/API/fetch#options))                                                                                         |
