| + | スキーマ | +生成される型 | +
|---|---|---|
| + ❌ 悪い + | ++ +```yaml +type: object +``` + + | +
+
+```ts
+Record |
+
| + ❌ 不十分 + | ++ +```yaml +type: object +additionalProperties: true +``` + + | +
+
+```ts
+Record |
+
| + ✅ 良い + | ++ +```yaml +type: object +additionalProperties: + type: string +``` + + | +
+
+```ts
+Record |
+
| + | スキーマ | +生成される型 | +
|---|---|---|
| + ❌ 悪い + | ++ +```yaml +type: array +``` + + | ++ +```ts +unknown[] +``` + + | +
| + ❌ 不十分 + | ++ +```yaml +type: array +items: + type: number +``` + + | ++ +```ts +number[] +``` + + | +
| + ✅ 良い + | ++ +```yaml +type: array +items: + type: number +maxItems: 2 +minItems: 2 +``` + +— または — + +```yaml +type: array +items: + type: number +prefixItems: + - number + - number +``` + + | ++ +```ts +[number, number]; +``` + + | +
+({ baseUrl: "https://myapi.dev/v1/" });
+
+const {
+ data, // 2XX レスポンスの場合のみ存在
+ error, // 4XX または 5XX レスポンスの場合のみ存在
+} = await client.GET("/blogposts/{post_id}", {
+ params: {
+ path: { post_id: "123" },
+ },
+});
+
+await client.PUT("/blogposts", {
+ body: {
+ title: "My New Post",
+ },
+});
+```
+
+:::
+
+
+
+openapi-fetch (推奨)
+ +::: code-group + +```ts [test/my-project.ts] +import createClient from "openapi-fetch"; +import type { paths } from "./my-openapi-3-schema"; // openapi-typescriptで生成された型 + +const client = createClient
+();
+
+// GET リクエストを送信
+const getBlogPost = fetcher.path("/blogposts/{post_id}").method("get").create();
+
+try {
+ const { status, data } = await getBlogPost({
+ pathParams: { post_id: "123" },
+ });
+ console.log(data);
+} catch (error) {
+ console.error("Error:", error);
+}
+
+// PUT リクエストを送信
+const updateBlogPost = fetcher.path("/blogposts").method("put").create();
+
+try {
+ await updateBlogPost({ body: { title: "My New Post" } });
+} catch (error) {
+ console.error("Error:", error);
+}
+```
+
+:::
+
+
+
+openapi-typescript-fetch by @ajaishankar
+ +::: code-group + +```ts [test/my-project.ts] +import { Fetcher } from "openapi-typescript-fetch"; +import type { paths } from "./my-openapi-3-schema"; // openapi-typescriptで生成された型 + +const fetcher = Fetcher.for
+({
+ prefixUrl: "https://myapi.dev/v1",
+});
+
+// GET リクエストを送信
+const response = await fetchClient.get("/blogposts/{post_id}", {
+ pathParams: {
+ post_id: "123",
+ },
+});
+
+// レスポンスを処理する（アプローチ1：標準のif-else）
+if (response.isOk()) {
+ const data = response.value.data;
+ console.log(data); // 成功したレスポンスを処理
+} else {
+ const error = response.error;
+ if (error instanceof NetworkError) {
+ console.error("Network error:", error.message);
+ } else if (error instanceof RequestError) {
+ console.error("Request error:", error.message, "Status:", error.status);
+ } else {
+ console.error("Service error:", error.message);
+ }
+}
+
+// PUT リクエストを送信
+const putResponse = await fetchClient.put("/blogposts", {
+ body: {
+ title: "My New Post",
+ },
+});
+
+// レスポンスを処理する（アプローチ2：try-catch）
+try {
+ const putData = putResponse.unwrap().data;
+ console.log(putData); // 成功したレスポンスを処理
+} catch (error) {
+ // エラーを処理
+ if (error instanceof NetworkError) {
+ console.error("Network error:", error.message);
+ } else if (error instanceof RequestError) {
+ console.error("Request error:", error.message, "Status:", error.status);
+ } else {
+ console.error("Service error:", error.message);
+ }
+}
+```
+
+:::
+
+
+
+::: tip
+
+良い fetch ラッパーは**ジェネリクスの使用は避ける**べきです。ジェネリクスは多くのタイプ指定が必要で、エラーを隠してしまう可能性があります！
+
+:::
+
+## Hono
+
+[Hono](https://hono.dev/)は、Node.js用のモダンなサーバーフレームワークで、エッジ環境（例：[Cloudflare Workers](https://developers.cloudflare.com/workers/)）や標準コンテナに簡単にデプロイできます。また、TypeScriptが組み込まれており、生成された型と非常に相性が良いです。
+
+[CLIを使用して型を生成](/ja/introduction)した後、各エンドポイントに適切な `paths` レスポンスを渡します：
+
+::: code-group
+
+```ts [src/my-project.ts]
+import { Hono } from "hono";
+import { components, paths } from "./my-openapi-3-schema"; // openapi-typescriptで生成された型
+
+const app = new Hono();
+
+/** /users */
+app.get("/users", async (ctx) => {
+ try {
+ const users = db.get("SELECT * from users");
+ return ctx.json<
+ paths["/users"]["responses"][200]["content"]["application/json"]
+ >(users);
+ } catch (err) {
+ return ctx.jsonfeature-fetch by builder.group
+ +::: code-group + +```ts [test/my-project.ts] +import { createOpenApiFetchClient } from "feature-fetch"; +import type { paths } from "./my-openapi-3-schema"; // openapi-typescriptで生成された型 + +// OpenAPI fetch クライアントを作成 +const fetchClient = createOpenApiFetchClient
+ = {
+ [K in keyof Obj]: K extends Matchers ? Obj[K] : never;
+}[keyof Obj];
+type PathResponses = T extends { responses: any } ? T["responses"] : unknown;
+type OperationContent = T extends { content: any } ? T["content"] : unknown;
+type MediaType = `${string}/${string}`;
+type MockedResponse =
+ FilterKeys, MediaType> extends never
+ ? { status: Status; body?: never }
+ : {
+ status: Status;
+ body: FilterKeys, MediaType>;
+ };
+
+/**
+ * fetch()呼び出しをモックし、OpenAPIスキーマに基づいて型を指定します
+ */
+export function mockResponses(responses: {
+ [Path in keyof Partial]: {
+ [Method in keyof Partial]: MockedResponse<
+ PathResponses
+ >;
+ };
+}) {
+ fetchMock.mockResponse((req) => {
+ const mockedPath = findPath(
+ req.url.replace(BASE_URL, ""),
+ Object.keys(responses)
+ )!;
+ // 注意: ここでの型は省略されており、この関数は`void`を返すシグネチャを持っています。重要なのはパラメータのシグネチャです。
+ if (!mockedPath || (!responses as any)[mockedPath])
+ throw new Error(`No mocked response for ${req.url}`); // モックされていない応答の場合はエラーをスローします（必要に応じて動作を変更してください）
+ const method = req.method.toLowerCase();
+ if (!(responses as any)[mockedPath][method])
+ throw new Error(`${req.method} called but not mocked on ${mockedPath}`); // 同様に、他の部分がモックされていない場合もエラーをスローします
+ if (!(responses as any)[mockedPath][method]) {
+ throw new Error(`${req.method} called but not mocked on ${mockedPath}`);
+ }
+ const { status, body } = (responses as any)[mockedPath][method];
+ return { status, body: JSON.stringify(body) };
+ });
+}
+
+// 現実的なURL（/users/123）をOpenAPIパス（/users/{user_id}）にマッチさせるヘルパー関数
+export function findPath(
+ actual: string,
+ testPaths: string[]
+): string | undefined {
+ const url = new URL(
+ actual,
+ actual.startsWith("http") ? undefined : "http://testapi.com"
+ );
+ const actualParts = url.pathname.split("/");
+ for (const p of testPaths) {
+ let matched = true;
+ const testParts = p.split("/");
+ if (actualParts.length !== testParts.length) continue; // 長さが異なる場合は自動的に一致しない
+ for (let i = 0; i < testParts.length; i++) {
+ if (testParts[i]!.startsWith("{")) continue; // パスパラメータ（{user_id}）は常に一致とみなされる
+ if (actualParts[i] !== testParts[i]) {
+ matched = false;
+ break;
+ }
+ }
+ if (matched) return p;
+ }
+}
+```
+
+:::
+
+::: info 追加の説明
+
+このコードはかなり複雑です！ 大部分は詳細な実装なので無視しても構いません。重要な仕掛けが行われているのは、`mockResponses(…)` 関数のシグネチャです。ここにすべての重要な処理が行われています—この構造と私たちの設計との直接的な関係が見えるでしょう。残りのコードはランタイムが期待通りに動作するように整えるだけです。
+
+:::
+
+```ts
+export function mockResponses(responses: {
+ [Path in keyof Partial]: {
+ [Method in keyof Partial]: MockedResponse<
+ PathResponses
+ >;
+ };
+});
+```
+
+
+
+これで、スキーマが更新されるたびに、**すべてのモックデータが正しく型チェックされる**ようになります 🎉。これは、堅牢で正確なテストを確保するための大きな一歩です。
diff --git a/docs/ja/index.md b/docs/ja/index.md
new file mode 100644
index 000000000..13a6e7660
--- /dev/null
+++ b/docs/ja/index.md
@@ -0,0 +1,53 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+ name: "OpenAPI TypeScript"
+ tagline: "OpenAPI 3.0/3.1 スキーマを TypeScriptの型に変換し、型安全なフェッチングを可能にします。"
+ actions:
+ - theme: brand
+ text: "始める"
+ link: /ja/introduction
+ - theme: alt
+ text: "GitHubで見る"
+ link: https://github.com/openapi-ts/openapi-typescript
+
+features:
+ - title: "超高速"
+ details: "静的な TypeScriptの型は、実行時に影響を与えず、クライアントの負担もありません。"
+ - title: "型安全"
+ details: "OpenAPI スキーマを使用して、セットアップやテストなしでコード全体を型チェックします。"
+ - title: "どこでも実行可能"
+ details: "TypeScript が実行できる場所ならどこでも使用可能。どのスタックやフレームワークでも動作します。"
+---
+
+📄 test/utils.ts
+ +::: code-group + +```ts [test/utils.ts] +import type { paths } from "./my-openapi-3-schema"; // openapi-typescriptで生成された型 + +// 設定 +// ⚠️ 重要: ここを変更してください！これはすべてのURLにプレフィックスを追加します +const BASE_URL = "https://myapi.com/v1"; +// 設定終了 + +// 型ヘルパー — これらはTSルックアップを改善するためのものです。無視しても構いません +type FilterKeys
+
+### 利用者
+
+
+
+-
+
+
+
+
+
+
+
+
+
+### スポンサー
+
+
+
+
diff --git a/docs/ja/introduction.md b/docs/ja/introduction.md
new file mode 100644
index 000000000..f93bd8148
--- /dev/null
+++ b/docs/ja/introduction.md
@@ -0,0 +1,112 @@
+---
+title: openapi-typescript
+description: クイックスタート
+---
+
+
+
+
+[OpenCollective](https://opencollective.com/openapi-ts) でスポンサーになり、このプロジェクトを支援しましょう!
+
+
+
+
+
+openapi-typescriptは、[OpenAPI 3.0 & 3.1](https://spec.openapis.org/oas/latest.html) スキーマをNode.jsを使用して素早くTypeScriptに変換します。Java/node-gyp/OpenAPIサーバーの実行は不要です。
+
+このコードは[MITライセンス](https://github.com/openapi-ts/openapi-typescript/blob/main/packages/openapi-typescript/LICENSE)で保護されており、無料で利用可能です。
+
+::: tip
+
+OpenAPI初心者ですか？Speakeasyの [Intro to OpenAPI](https://www.speakeasyapi.dev/openapi) は、初心者にも分かりやすいガイドで、OpenAPIの「なぜ」と「どのように」を説明しています。
+
+:::
+
+## 特徴
+
+- ✅ OpenAPI 3.0および3.1をサポート（[discriminators](https://spec.openapis.org/oas/v3.1.0#discriminator-object)のような高度な機能を含む）
+- ✅ 従来のコード生成より優れている**実行時に依存しない型**を生成
+- ✅ YAMLまたはJSONから、ローカルまたはリモートでスキーマを読み込む
+- ✅ 巨大なスキーマであってもミリ秒単位で型を生成
+
+_注: OpenAPI 2.xはバージョン `5.x` およびそれ以前でサポートされています_
+
+## 使用例
+
+👀 [使用例を見る](https://github.com/openapi-ts/openapi-typescript/blob/main/packages/openapi-typescript/examples/)
+
+## セットアップ
+
+このライブラリを使用するには、最新バージョンの [Node.js](https://nodejs.org) がインストールされている必要があります（20.x 以上を推奨）。インストールしたら、以下のコマンドをプロジェクトで実行してください：
+
+```bash
+npm i -D openapi-typescript typescript
+```
+
+次に、`tsconfig.json` ファイルに以下を追加して、型を正しく読み込めるようにします：
+
+::: code-group
+
+```json [tsconfig.json]
+{
+ "compilerOptions": {
+ "module": "ESNext", // または "NodeNext" // [!code ++]
+ "moduleResolution": "Bundler" // または "NodeNext" // [!code ++]
+ }
+}
+```
+
+:::
+
+::: tip 強く推奨
+
+さらに、以下の設定を追加すると型の安全性が向上します：
+
+::: code-group
+
+```json [tsconfig.json]
+{
+ "compilerOptions": {
+ "noUncheckedIndexedAccess": true // [!code ++]
+ }
+}
+```
+
+:::
+
+## 基本的な使い方
+
+まず、`npx openapi-typescript` を実行してローカルの型ファイルを生成します。最初に入力スキーマ（JSON または YAML）を指定し、保存する場所を `--output` （`-o`）で指定します：
+
+```bash
+# ローカルスキーマ
+npx openapi-typescript ./path/to/my/schema.yaml -o ./path/to/my/schema.d.ts
+# 🚀 ./path/to/my/schema.yaml -> ./path/to/my/schema.d.ts [7ms]
+
+# リモートスキーマ
+npx openapi-typescript https://myapi.dev/api/v1/openapi.yaml -o ./path/to/my/schema.d.ts
+# 🚀 https://myapi.dev/api/v1/openapi.yaml -> ./path/to/my/schema.d.ts [250ms]
+```
+
+次に、TypeScript プロジェクトで必要に応じて型をインポートします：
+
+::: code-group
+
+```ts [src/my-project.ts]
+import type { paths, components } from "./my-openapi-3-schema"; // openapi-typescript によって生成
+
+// スキーマオブジェクト
+type MyType = components["schemas"]["MyType"];
+
+// パスパラメータ
+type EndpointParams = paths["/my/endpoint"]["parameters"];
+
+// レスポンスオブジェクト
+type SuccessResponse =
+ paths["/my/endpoint"]["get"]["responses"][200]["content"]["application/json"]["schema"];
+type ErrorResponse =
+ paths["/my/endpoint"]["get"]["responses"][500]["content"]["application/json"]["schema"];
+```
+
+:::
+
+ここから、これらの型を以下の用途で使用できます（ただし、これに限定されません）：
+
+- OpenAPI対応のfetchクライアントを使用する（例：[openapi-fetch](/ja/openapi-fetch/)）
+- 他のAPIリクエストボディやレスポンスの型のアサート
+- API型に基づいたコアビジネスロジックの構築
+- モックテストデータが現在のスキーマと一致していることを確認する
+- 任意のnpmパッケージ（クライアントSDKなど）にAPI型をパッケージ化する
diff --git a/docs/ja/migration-guide.md b/docs/ja/migration-guide.md
new file mode 100644
index 000000000..2327effa7
--- /dev/null
+++ b/docs/ja/migration-guide.md
@@ -0,0 +1,56 @@
+---
+title: マイグレーションガイド
+description: openapi-typescript のバージョン間の移行
+---
+
+# 7.x への移行
+
+7.x リリースには、注意すべきいくつかの軽微な破壊的変更があります：
+
+### 認証 / リモートスキーマの取得
+
+7.x では、すべてのリモートスキーマの取得が [Redocly CLI](https://redocly.com/docs/developer-portal/guides/reference-docs-integration-advanced/#authentication) によって処理されます。これにより、認証設定を `redocly.config.yml` 設定ファイルに[移行](https://redocly.com/docs/developer-portal/guides/reference-docs-integration-advanced/#authentication)する必要があります（[ドキュメント](https://redocly.com/docs/developer-portal/guides/reference-docs-integration-advanced/#authentication)を参照）。
+
+### TypeScript AST
+
+7.x では、単純な文字列変換の代わりに TypeScript AST が導入されました。これは、TypeScript ASTを返すようになったコアのNode.js API、および `transform()` や `postTransform()` オプションに適用されます。[Node.js API のドキュメントが、関連する例と共に更新されています](./node)。
+
+### defaultNonNullableがデフォルトで true
+
+CLI および Node.js API では、`--default-non-nullable` の動作がデフォルトで有効になりました。これにより、スキーマオブジェクトに `default` 値がある場合、それは `required` として扱われます（parametersを除く）。
+
+### Redocly 設定ファイルによる globbing の置き換え
+
+7.x では複数のスキーマを一度に生成することができますが、特定の命名スキーマに従うことを強制するグロビングの代わりに、`redocly.config.yaml` ファイルを宣言して、各入力スキーマとその関連する生成された型の保存場所を指定します。これにより、複数のスキーマの命名と整理に柔軟性が生まれます。
+
+便利なことに、`redocly.config.yml` ファイルを宣言しておけば、引数なしで CLI コマンドを実行できます（[ドキュメント](./cli#redoc-config)参照）：
+
+```sh
+npx openapi-typescript
+```
+
+### Node.js API のinputの型
+
+7.x ではinputの型が調整され、より予測可能で汎用的になりました。
+
+```ts
+import openapiTS from "openapi-typescript";
+
+await openapiTS(input);
+```
+
+| Input | 6.x | 7.x |
+| :------------ | :-------------: | :------: |
+| JSON (object) | `Object` | `Object` |
+| JSON (string) | (未サポート) | `string` |
+| YAML (string) | (未サポート) | `string` |
+| Local file | `string \| URL` | `URL` |
+| Remote file | `string \| URL` | `URL` |
+
+最大の変更点は `string` の扱いです。6.x では、string はローカルまたはリモートのファイルパスを指す可能性がありましたが、これは予測不可能でした。というのも、ローカルファイルパスの場合、Node が呼び出された場所に依存していたからです。7.x では、**すべてのファイルパスは [URL](https://nodejs.org/api/url.html) である必要があります**（ローカルパスの場合、`new URL('./path/to/my/schema', import.meta.url)` または `new URL('file:///absolute/path/to/my/schema')` を使用）。これにより、 `string` 型がインライン YAML（または JSON）を扱えるようになりました（6.x ではサポートされていませんでした）。
+
+[詳細は更新されたドキュメントを参照](./node#使用方法)。
+
+---
+
+[完全な変更履歴はこちら](https://github.com/openapi-ts/openapi-typescript/blob/6.x/packages/openapi-typescript/CHANGELOG.md)
diff --git a/docs/ja/node.md b/docs/ja/node.md
new file mode 100644
index 000000000..2fedf1716
--- /dev/null
+++ b/docs/ja/node.md
@@ -0,0 +1,263 @@
+---
+title: openapi-typescript Node.js API
+description: プログラムでの使用と無限の柔軟性。
+---
+
+# Node.js API
+
+Node APIは、動的に生成されたスキーマを扱う場合や、より大きなアプリケーションのコンテキスト内で使用する場合に役立ちます。メモリからスキーマをロードするためにJSONフレンドリーなオブジェクトを渡すか、ローカルファイルやリモートURLからスキーマをロードするために文字列を渡します。
+
+## セットアップ
+
+```bash
+npm i --save-dev openapi-typescript typescript
+```
+
+::: tip 推奨
+
+最適な体験を得るために、 `"type": "module"` を `package.json` に追加して Node ESM を使用してください([ドキュメント](https://nodejs.org/api/esm.html#enabling))
+
+:::
+
+## 使用方法
+
+Node.js APIは、`URL`、`string`、またはJSONオブジェクトを入力として受け付けます：
+
+| タイプ | 説明 | 例 |
+| :------: | :--------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------- |
+| `URL` | ローカルまたはリモートファイルを読み取る | `await openapiTS(new URL('./schema.yaml', import.meta.url))``await openapiTS(new URL('https://myapi.com/v1/openapi.yaml'))` | +| `string` | 動的なYAMLまたはJSONを読み取る | `await openapiTS('openapi: "3.1" … ')` | +| `JSON` | 動的なJSONを読み取る | `await openapiTS({ openapi: '3.1', … })` | + +また、 `Readable` ストリームや`Buffer` 型も受け付け、これらは文字列として解決されます（ドキュメント全体がないと検証、バンドル、型生成ができません）。 + +Node APIはTypeScript の AST を含む `Promise` を返します。その後、必要に応じてASTをトラバース、操作、または修正できます。 + +TypeScript ASTを文字列に変換するには、[TypeScriptのprinterのラッパー](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API#re-printing-sections-of-a-typescript-file)である `astToString()` ヘルパーを使用できます: + +::: code-group + +```ts [src/my-project.ts] +import fs from "node:fs"; +import openapiTS, { astToString } from "openapi-typescript"; + +const ast = await openapiTS(new URL("./my-schema.yaml", import.meta.url)); +const contents = astToString(ast); + +// （任意）ファイルに書き込み +fs.writeFileSync("./my-schema.ts", contents); +``` + +::: + +### Redoc config + +Redoc configはopenapi-typescriptを使用するために必須ではありません。デフォルトでは `"minimal"` ビルトイン設定を拡張しますが、デフォルト設定を変更したい場合は、完全に初期化されたRedoc configをNode APIに提供する必要があります。これを行うには、`@redocly/openapi-core` のヘルパーを使用できます： + +::: code-group + +```ts [src/my-project.ts] +import { createConfig, loadConfig } from "@redocly/openapi-core"; +import openapiTS from "openapi-typescript"; + +// オプション1： インメモリ設定を作成 +const redocly = await createConfig( + { + apis: { + "core@v2": { … }, + "external@v1": { … }, + }, + }, + { extends: ["recommended"] }, +); + +// オプション2： redocly.yamlファイルから読み込み +const redocly = await loadConfig({ configPath: "redocly.yaml" }); + +const ast = await openapiTS(mySchema, { redocly }); +``` + +::: + +## オプション + +Node APIは、 `camelCase` 形式で[CLI フラグ](./cli#%E3%83%95%E3%83%A9%E3%82%AF%E3%82%99) すべてをサポートしており、以下の追加オプションも利用可能です： + +| 名前 | タイプ | デフォルト | 説明 | +| :-------------- | :-------------: | :-------------: | :------------------------------------------------------------------------------------------- | +| `transform` | `Function` | | 特定の状況でデフォルトのスキーマオブジェクトをTypeScriptにするトランスフォーマーを上書きする | +| `postTransform` | `Function` | | `transform` と同じだが、TypeScript変換後に実行される | +| `silent` | `boolean` | `false` | 警告メッセージを非表示にする（致命的なエラーは表示されます） | +| `cwd` | `string \| URL` | `process.cwd()` | （オプション）必要に応じてリモート$refの解決を支援するために現在の作業ディレクトリを指定 | +| `inject` | `string` | | ファイルの先頭に任意のTypeScript型を注入 | + +### transform / postTransform + +`transform()` と `postTransform()` オプションを使用して、デフォルトのスキーマオブジェクト変換を独自のものに上書きできます。これは、スキーマの特定の部分に対して非標準的な変更を提供する場合に役立ちます。 + +- `transform()` はTypeScriptへの **変換前** に実行されます（OpenAPIノードを扱います） +- `postTransform()` はTypeScriptへの **変換後** に実行されます（TypeScript ASTを扱います） + +#### 例: `Date` 型 + +例えば、スキーマに次のプロパティが含まれているとします： + +```yaml +properties: + updated_at: + type: string + format: date-time +``` + +デフォルトでは、openapiTSは`updated_at?: string;`を生成します。これは、`"date-time"`がどのフォーマットを意味するのかが明確でないためです（フォーマットは標準化されておらず、任意の形式にできるため）。しかし、独自のカスタムフォーマッタを提供することで、これを改善できます。例えば次のようにします： + +::: code-group + +```ts [src/my-project.ts] +import openapiTS from "openapi-typescript"; +import ts from "typescript"; + +const DATE = ts.factory.createTypeReferenceNode( + ts.factory.createIdentifier("Date") +); // `Date` +const NULL = ts.factory.createLiteralTypeNode(ts.factory.createNull()); // `null` + +const ast = await openapiTS(mySchema, { + transform(schemaObject, metadata) { + if (schemaObject.format === "date-time") { + return schemaObject.nullable + ? ts.factory.createUnionTypeNode([DATE, NULL]) + : DATE; + } + }, +}); +``` + +::: + +その結果、以下のようになります： + +::: code-group + +```yaml [my-openapi-3-schema.yaml] +updated_at?: string; // [!code --] +updated_at: Date | null; // [!code ++] +``` + +::: + +#### 例: `Blob` 型 + +もう一つの一般的な変換は、リクエストの `body` が `multipart/form-data` で、いくつかの `Blob` フィールドを持つファイルアップロードの場合です。例えば次のようなスキーマがあります + +::: code-group + +```yaml [my-openapi-3-schema.yaml] +Body_file_upload: + type: object; + properties: + file: + type: string; + format: binary; +``` + +::: + +同じパターンを使用して型を変換します： + +::: code-group + +```ts [src/my-project.ts] +import openapiTS from "openapi-typescript"; +import ts from "typescript"; + +const BLOB = ts.factory.createTypeReferenceNode( + ts.factory.createIdentifier("Blob") +); // `Blob` +const NULL = ts.factory.createLiteralTypeNode(ts.factory.createNull()); // `null` + +const ast = await openapiTS(mySchema, { + transform(schemaObject, metadata) { + if (schemaObject.format === "binary") { + return schemaObject.nullable + ? ts.factory.createUnionTypeNode([BLOB, NULL]) + : BLOB; + } + }, +}); +``` + +::: + +fileプロパティが正しく型付けされた差分は次のようになります： + +::: code-group + +```ts [my-openapi-3-schema.d.ts] +file?: string; // [!code --] +file: Blob | null; // [!code ++] +``` + +::: + +#### 例: プロパティに "?" トークンを追加 + +上記の `transform` 関数では、オプションの"?"トークンを持つプロパティを作成することはできません。しかし、transform関数は異なる戻りオブジェクトを受け入れることもでき、これを使用してプロパティに”?“トークンを追加することができます。以下はその例です： + +::: code-group + +```yaml [my-openapi-3-schema.yaml] +Body_file_upload: + type: object; + properties: + file: + type: string; + format: binary; + required: true; +``` + +::: + +ここではスキーマプロパティを持つオブジェクトを返しますが、これに加えて `questionToken` プロパティを追加し、プロパティに"?"トークンを追加します。 + +::: code-group + +```ts [src/my-project.ts] +import openapiTS from "openapi-typescript"; +import ts from "typescript"; + +const BLOB = ts.factory.createTypeReferenceNode( + ts.factory.createIdentifier("Blob") +); // `Blob` +const NULL = ts.factory.createLiteralTypeNode(ts.factory.createNull()); // `null` + +const ast = await openapiTS(mySchema, { + transform(schemaObject, metadata) { + if (schemaObject.format === "binary") { + return { + schema: schemaObject.nullable + ? ts.factory.createUnionTypeNode([BLOB, NULL]) + : BLOB, + questionToken: true, + }; + } + }, +}); +``` + +::: + +`file` プロパティが正しく型付けされ、"?"トークンが追加された結果の差分は次のとおりです： + +::: code-group + +```ts [my-openapi-3-schema.d.ts] +file: Blob; // [!code --] +file?: Blob | null; // [!code ++] +``` + +::: + +スキーマ内の任意の[Schema Object](https://spec.openapis.org/oas/latest.html#schema-object)は、このフォーマッタを通じて処理されます（リモートのものも含まれます!）。また、追加のコンテキストが役立つ場合があるので、`metadata` パラメータも必ず確認してください。 + +`format`のチェック以外にも、これを利用する方法は多数あります。この関数は **string** を返す必要があるため、任意のTypeScriptコード（独自のカスタム型も含む）を生成することができます。 diff --git a/docs/ja/openapi-fetch/about.md b/docs/ja/openapi-fetch/about.md new file mode 100644 index 000000000..783aaf5b8 --- /dev/null +++ b/docs/ja/openapi-fetch/about.md @@ -0,0 +1,48 @@ +--- +title: openapi-fetch について +description: openapi-fetch プロジェクトの目標、比較など +--- + + + +# openapi-fetch について + +## プロジェクトの目標 + +1. 型は厳密で、最小限のジェネリクスで OpenAPI スキーマから自動的に推論されるべきです。 +2. ネイティブの Fetch API を尊重しつつ、（`await res.json()` などの）ボイラープレートを削減すること。 +3. 可能な限り軽量で高性能であること。 + +## 比較 + +### vs. Axios + +[Axios](https://axios-http.com) は、OpenAPI スキーマに対して自動的に型チェックを行うことはできません。さらに、それを実現する簡単な方法もありません。Axios は、インターセプターや高度なキャンセルなど、openapi-fetch よりも多くの機能を備えています。 + +### vs. tRPC + +[tRPC](https://trpc.io/) は、バックエンドとフロントエンドが両方とも TypeScript (Node.js) で書かれているプロジェクト向けです。openapi-fetch はユニバーサルであり、OpenAPI 3.x スキーマに従う任意のバックエンドと連携することができます。 + +### vs. openapi-typescript-fetch + +[openapi-typescript-fetch](https://github.com/ajaishankar/openapi-typescript-fetch) は、openapi-fetch よりも前に開発され、目的はほぼ同じですが、主に構文が異なります（つまり、選択は好みに依存します）: + +- openapi-typescript-fetch は非 OK 応答の場合に例外を投げます（そのため、`try/catch` でラップする必要があります）。これに対して openapi-fetch は Fetch API 仕様に従い、例外を投げません。 +- openapi-typescript-fetch の構文は冗長で、チェーン（`.path(…).method(…).create()`）に依存します。 + +### vs. openapi-typescript-codegen + +[openapi-typescript-codegen](https://github.com/ferdikoomen/openapi-typescript-codegen) はコード生成ライブラリであり、openapi-fetch の「コード生成なし」アプローチとは根本的に異なります。openapi-fetch は、ビルド時に静的な TypeScript 型チェックを行い、クライアントの負担を増やさず、ランタイムでのパフォーマンスに影響を与えません。従来のコード生成は、クライアントの負担を増やし、ランタイムを遅くする何百（あるいは何千）もの異なる関数を生成します。 + +### vs. Swagger Codegen + +Swagger Codegen は Swagger/OpenAPI の元祖のコード生成プロジェクトであり、他のコード生成アプローチと同様にサイズの膨張やランタイムのパフォーマンス問題があります。さらに、Swagger Codegen は Java ランタイムが必要ですが、openapi-typescript/openapi-fetch はネイティブの Node.js プロジェクトとしてその必要がありません。 + +## 貢献者 + +これらの素晴らしい貢献者がいなければ、このライブラリは存在しなかったでしょう： + +
+
+openapi-fetchは、あなたのOpenAPIスキーマを取り込み、型安全なfetchクライアントを提供します。このライブラリはわずか **6 kb** で、ほとんどのランタイムを持たず、React、Vue、Svelte、あるいはバニラJSとも動作します。
+
+| ライブラリ | サイズ (min) | “GET” リクエスト\* |
+| :------------------------- | -----------: | :----------------------- |
+| openapi-fetch | `6 kB` | `300k` ops/s (最速) |
+| openapi-typescript-fetch | `3 kB` | `300k` ops/s (最速) |
+| feature-fetch | `15 kB` | `300k` ops/s (最速) |
+| axios | `32 kB` | `225k` ops/s (1.3倍遅い) |
+| superagent | `55 kB` | `50k` ops/s (6倍遅い) |
+| openapi-typescript-codegen | `367 kB` | `100k` ops/s (3倍遅い) |
+
+_\* [ベンチマークはおおよそのものです](https://github.com/openapi-ts/openapi-typescript/blob/main/packages/openapi-fetch/test/index.bench.js) 。実際のパフォーマンスはマシンやブラウザによって異なる場合があります。ライブラリ間の相対的なパフォーマンスはより信頼性があります。_
+
+このシンタックスは、React QueryやApollo Clientのような人気のライブラリにインスパイアされたものでありながら、すべての装飾を省き、6 kbというコンパクトなパッケージに収まっています。
+
+::: code-group
+
+```ts [src/my-project.ts]
+import createClient from "openapi-fetch";
+import type { paths } from "./my-openapi-3-schema"; // openapi-typescriptで生成された型
+
+const client = createClientNew post body
", + publish_date: new Date("2023-03-01T12:00:00Z").getTime(), + }, +}); +``` + +::: + +1. HTTPメソッドを `createClient()` から直接取得します。 +2. `GET()` , `PUT()` などに希望する `path` を渡します。 +3. TypeScriptが欠落しているものや無効なものがあれば有用なエラーを返します。 + +### Pathname + +`GET()` , `PUT()` , `POST()` などのpathnameは、**スキーマと厳密に一致している必要があります**。例では、URLは `/blogposts/{post_id}` です。このライブラリは、すべての `path` パラメータをすぐに置き換え、それらが型チェックされるようにします。 + +::: tip + +openapi-fetch は URL から型を推論します。動的な実行時の値よりも静的な文字列値を優先してください。例： + +- ✅ `"/blogposts/{post_id}"` +- ❌ `[...pathParts].join("/") + "{post_id}"` + +::: + +このライブラリはまた、**label** および **matrix** のシリアライゼーションスタイルもサポートしています（[ドキュメント](https://swagger.io/docs/specification/serialization/#path)）。 + +### Request + +`GET()` リクエストには、[タイプごとにパラメータをグループ化する](https://spec.openapis.org/oas/latest.html#parameter-object) `params` オブジェクトが必要です（ `path`または `query` ）。必須のパラメータが欠けている場合や、型が間違っている場合には、型エラーが発生します。 + +`POST()` リクエストでは、必要な [requestBody](https://spec.openapis.org/oas/latest.html#request-body-object) データを提供する `body` オブジェクトが必要でした。 + +### Response + +すべてのメソッドは**data**、**error**および **response**を持つオブジェクトを返します。 + +```ts +const { data, error, response } = await client.GET("/url"); +``` + +| Object | Response | +| :--------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `data` | OKの場合 `2xx` レスポンス、そうでない場合 `undefined` | +| `error` | OKでない場合 `5xx` 、`4xx` 、または `default` レスポンス、それ以外は `undefined` | +| `response` | [オリジナルのレスポンス](https://developer.mozilla.org/en-US/docs/Web/API/Response)であり、`status`, `headers` などを含みます。 | + +### Path-property スタイル + +パスをプロパティとして選択する方が好ましい場合は、パスベースのクライアントを作成できます： + +```ts +import { createPathBasedClient } from "openapi-fetch"; +import type { paths } from "./my-openapi-3-schema"; // openapi-typescriptで生成された型 + +const client = createPathBasedClient{data.title}
;
+};
+```
+
+:::
+
+## セットアップ
+
+このライブラリを [openapi-fetch](../openapi-fetch/) および [openapi-typescript](../introduction) と一緒にインストールします：
+
+```bash
+npm i openapi-react-query openapi-fetch
+npm i -D openapi-typescript typescript
+```
+
+::: tip 強く推奨
+
+`tsconfig.json`で [noUncheckedIndexedAccess](https://www.typescriptlang.org/tsconfig#noUncheckedIndexedAccess) を有効にしてください ([ドキュメント](/ja/advanced#tsconfigで-nouncheckedindexedaccess-を有効にする))
+
+:::
+
+次に、openapi-typescript を使用してOpenAPIスキーマからTypeScriptの型を生成します：
+
+```bash
+npx openapi-typescript ./path/to/api/v1.yaml -o ./src/lib/api/v1.d.ts
+```
+
+## 基本的な使い方
+
+スキーマから型が生成されたら、[fetch クライアント](../introduction.md)と react-query クライアントを作成し、API にクエリを実行できます。
+
+::: code-group
+
+```tsx [src/my-component.ts]
+import createFetchClient from "openapi-fetch";
+import createClient from "openapi-react-query";
+import type { paths } from "./my-openapi-3-schema"; // openapi-typescriptで生成された型
+
+const fetchClient = createFetchClient{data.title}
;
+};
+```
+
+:::
+
+::: tip
+`createFetchClient` に関する詳細は [openapi-fetch ドキュメント](../openapi-fetch/index.md) をご覧ください。
+:::
diff --git a/docs/ja/openapi-react-query/use-mutation.md b/docs/ja/openapi-react-query/use-mutation.md
new file mode 100644
index 000000000..4172efed1
--- /dev/null
+++ b/docs/ja/openapi-react-query/use-mutation.md
@@ -0,0 +1,68 @@
+---
+title: useMutation
+---
+
+# {{ $frontmatter.title }}
+
+`useMutation` メソッドを使用すると、react-query 本来の [useMutation](https://tanstack.com/query/latest/docs/framework/react/guides/mutations) を利用できます。
+
+- result は本来の関数と同じです。
+- `mutationKey` は `[method, path]`です。
+- `data` と `error` は完全に型付けされています。
+
+::: tip
+`useMutation` に関する詳細は、[@tanstack/react-query ドキュメント](https://tanstack.com/query/latest/docs/framework/react/guides/mutations) で確認できます。
+:::
+
+## 使用例
+
+::: code-group
+
+```tsx [src/app.tsx]
+import { $api } from "./api";
+
+export const App = () => {
+ const { mutate } = $api.useMutation("patch", "/users");
+
+ return (
+
+ );
+};
+```
+
+```ts [src/api.ts]
+import createFetchClient from "openapi-fetch";
+import createClient from "openapi-react-query";
+import type { paths } from "./my-openapi-3-schema"; // openapi-typescriptで生成された型
+
+const fetchClient = createFetchClient{data.firstname}
;
+};
+```
+
+```ts [src/api.ts]
+import createFetchClient from "openapi-fetch";
+import createClient from "openapi-react-query";
+import type { paths } from "./my-openapi-3-schema"; // openapi-typescriptで生成された型
+
+const fetchClient = createFetchClient{data.firstname}
;
+};
+
+export const App = () => {
+ return (
+