openapi-typescript | OpenAPI TypeScript

openapi-typescriptは、OpenAPI 3.0 & 3.1 スキーマをNode.jsを使用して素早くTypeScriptに変換します。Java/node-gyp/OpenAPIサーバーの実行は不要です。

このコードはMITライセンスで保護されており、無料で利用可能です。

TIP

OpenAPI初心者ですか？Speakeasyの Intro to OpenAPI は、初心者にも分かりやすいガイドで、OpenAPIの「なぜ」と「どのように」を説明しています。

特徴

✅ OpenAPI 3.0および3.1をサポート（discriminatorsのような高度な機能を含む）
✅ 従来のコード生成より優れている実行時に依存しない型を生成
✅ YAMLまたはJSONから、ローカルまたはリモートでスキーマを読み込む
✅ 巨大なスキーマであってもミリ秒単位で型を生成

注: OpenAPI 2.xはバージョン 5.x およびそれ以前でサポートされています

使用例

👀 使用例を見る

セットアップ

このライブラリを使用するには、最新バージョンの Node.js がインストールされている必要があります（20.x 以上を推奨）。インストールしたら、以下のコマンドをプロジェクトで実行してください：

bash

npm i -D openapi-typescript typescript

次に、tsconfig.json ファイルに以下を追加して、型を正しく読み込めるようにします：

tsconfig.json

json

{
  "compilerOptions": {
    "module": "ESNext", // または "NodeNext"
    "moduleResolution": "Bundler" // または "NodeNext"
  }
}

強く推奨

さらに、以下の設定を追加すると型の安全性が向上します：

tsconfig.json

json

{
  "compilerOptions": {
    "noUncheckedIndexedAccess": true
  }
}

基本的な使い方

まず、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 プロジェクトで必要に応じて型をインポートします：

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）
他のAPIリクエストボディやレスポンスの型のアサート
API型に基づいたコアビジネスロジックの構築
モックテストデータが現在のスキーマと一致していることを確認する
任意のnpmパッケージ（クライアントSDKなど）にAPI型をパッケージ化する

特徴 ​

使用例 ​

セットアップ ​

基本的な使い方 ​

特徴

使用例

セットアップ

基本的な使い方