diff --git a/docs/ja/cli.md b/docs/ja/cli.md index 94666e5c2..fc662bbf0 100644 --- 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 index bd1136b92..0e761d0e5 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -142,6 +142,82 @@ try { +
+openapi-axios by @web-bee-ru + +::: 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(axios, { validStatus: "axios" }); + +// const api = new OpenApiAxios(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(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(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 のエラー +} +``` + +::: + +
+ ::: tip 良い fetch ラッパーは**ジェネリクスの使用は避ける**べきです。ジェネリクスは多くのタイプ指定が必要で、エラーを隠してしまう可能性があります！ diff --git a/docs/ja/openapi-fetch/api.md b/docs/ja/openapi-fetch/api.md index 5979e6d9a..cfe549f14 100644 --- 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 index bc4539f59..ce19e255f 100644 --- 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)) |