From ad854a0885d0e40d56bd7339e6c9342414c830ae Mon Sep 17 00:00:00 2001 From: Hikaru Yoshino Date: Sat, 21 Sep 2024 16:10:36 +0900 Subject: [PATCH 1/5] docs(ja): add `--root-types` to cli flags, a9cd9aa56dd9dec043a4e4fd85527acac227a142 --- docs/ja/cli.md | 1 + 1 file changed, 1 insertion(+) 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 From 1ca5cd301b1bdbe6a08089aa6d43cce5349447ea Mon Sep 17 00:00:00 2001 From: Hikaru Yoshino Date: Sat, 21 Sep 2024 16:16:22 +0900 Subject: [PATCH 2/5] docs(ja): add `web-bee-ru/openapi-axios` to examples, 4fc9588cabe985e316ec4aaa8657abf310ba0938 --- docs/ja/examples.md | 76 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) diff --git a/docs/ja/examples.md b/docs/ja/examples.md index bd1136b92..f4fcbb69f 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 ラッパーは**ジェネリクスの使用は避ける**べきです。ジェネリクスは多くのタイプ指定が必要で、エラーを隠してしまう可能性があります！ From ac4b52209fcf5066543d45311c4b5ec919735a61 Mon Sep 17 00:00:00 2001 From: Hikaru Yoshino Date: Sat, 21 Sep 2024 16:53:29 +0900 Subject: [PATCH 3/5] docs(ja): add tip on openapi-fetch Content-Type, b893c44f4290917f24c2ef7cda106c540df9cb3d --- docs/ja/openapi-fetch/api.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/ja/openapi-fetch/api.md b/docs/ja/openapi-fetch/api.md index 5979e6d9a..5602e83da 100644 --- a/docs/ja/openapi-fetch/api.md +++ b/docs/ja/openapi-fetch/api.md @@ -180,6 +180,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スキーマ内の特定のフォーマットに基づいて自動的に行われます。 From dd3a273d719e46527e440a44627ee11b2878d06b Mon Sep 17 00:00:00 2001 From: Hikaru Yoshino Date: Sat, 21 Sep 2024 16:59:25 +0900 Subject: [PATCH 4/5] docs(ja): add `baseUrl` to fetch options, 2a4b067f43f7e0b75aecbf5c2fb3013a4e96e591 --- docs/ja/openapi-fetch/api.md | 1 + docs/openapi-fetch/api.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/ja/openapi-fetch/api.md b/docs/ja/openapi-fetch/api.md index 5602e83da..c0a15697e 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)) | 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)) | From 60dc0b8485b00828cb777bfd5fed07dc9e9bc10e Mon Sep 17 00:00:00 2001 From: Hikaru Yoshino Date: Sat, 21 Sep 2024 18:39:58 +0900 Subject: [PATCH 5/5] docs(ja): fix a few expressions --- docs/ja/examples.md | 6 +++--- docs/ja/openapi-fetch/api.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/ja/examples.md b/docs/ja/examples.md index f4fcbb69f..0e761d0e5 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -159,7 +159,7 @@ const axios = Axios.create({ // 例1. "axios"（デフォルト）のステータス処理方法での使用 (validStatus: 'axios') -// axiosのようにエラーを投げる（例：status >= 400、ネットワークエラー、インターセプターエラー） +// axiosのようにエラーをスローする（例：status >= 400、ネットワークエラー、インターセプターエラー） const api = new OpenApiAxios(axios, { validStatus: "axios" }); // const api = new OpenApiAxios(axios) // 同じ結果になる @@ -178,7 +178,7 @@ try { // 例2. "fetch" ステータス処理方法での使用 (validStatus: 'fetch') -// ブラウザのfetch()のようにエラーを投げる（例：ネットワークエラー、インターセプターエラー） +// ブラウザのfetch()のようにエラーをスローする（例：ネットワークエラー、インターセプターエラー） const fetchApi = new OpenApiAxios(axios, { validStatus: "fetch", }); @@ -208,7 +208,7 @@ if (error) { if (typeof status === "number") { // status >= 400 } else if (api.isAxiosError(error)) { - // リクエスト失敗（例：ネットワークエラー + // リクエスト失敗（例：ネットワークエラー) } throw error; // axios.interceptors のエラー } diff --git a/docs/ja/openapi-fetch/api.md b/docs/ja/openapi-fetch/api.md index c0a15697e..cfe549f14 100644 --- a/docs/ja/openapi-fetch/api.md +++ b/docs/ja/openapi-fetch/api.md @@ -183,7 +183,7 @@ const { data, error } = await client.PUT("/submit", { ::: tip -便宜上、 `openapi-fetch` は `body` パラメーターに値が指定されたリクエストに対して、`Content-Type` を自動的に `application/json` に設定します。 +便宜上、`openapi-fetch` は `body` パラメーターに値が指定されたリクエストに対して、`Content-Type` を `application/json` に自動で設定します。 `bodySerializer` が `FormData` のインスタンスを返す場合、`Content-Type` ヘッダーは省略され、ブラウザがメッセージの複数のパートを正しく区切るboundaryを含む `Content-Type` を自動的に設定します。 また、fetch オプションやクライアントのインスタンス化時に、`headers` オブジェクトを通じて `Content-Type` を手動で設定することもできます。