CLI

CLI は、openapi-typescript を使用する最も一般的な方法です。CLI は JSON および YAML を解析でき、Redocly CLI を使用してスキーマを検証することもできます。ローカルおよびリモートのスキーマを解析可能です（基本認証もサポートしています）。

OpenAPI スキーマを TypeScript に変換する

単一スキーマ

スキーマを変換する最も簡単な方法は、入力スキーマ（JSON または YAML）を指定し、--output（-o）で出力先を指定することです：

npx openapi-typescript schema.yaml -o schema.ts

# 🚀 schema.yaml -> schema.ts [50ms]

npx openapi-typescript https://petstore3.swagger.io/api/v3/openapi.yaml -o petstore.d.ts

# 🚀 https://petstore3.swagger.io/api/v3/openapi.yaml -> petstore.d.ts [250ms]

複数のスキーマ

複数のスキーマを変換するには、プロジェクトのルートディレクトリに redocly.yaml ファイルを作成し、APIs を定義します。apis の下に、それぞれのスキーマに一意の名前と、必要に応じてオプションのバージョンを指定します（名前は一意であれば問題ありません）。root の値をスキーマのエントリーポイントに設定します。これが主な入力として機能します。出力については、x-openapi-ts.output で設定します：

redocly.yaml

apis:
  core@v2:
    root: ./openapi/openapi.yaml
    x-openapi-ts:
      output: ./openapi/openapi.ts
  external@v1:
    root: ./openapi/external.yaml
    x-openapi-ts:
      output: ./openapi/external.ts

TIP

これにより、スキーマの 1:1 入力:出力が保持されます。複数のスキーマを1つにまとめるには、Redocly の bundle コマンドを使用してください。

プロジェクト内に apis を含む redocly.yaml ファイルがあれば、CLI で入力/出力パラメータを省略できます：

npx openapi-typescript

WARNING

以前のバージョンでは globbing がサポートされていましたが、v7 では廃止され、代わりに redocly.yaml が推奨されるようになりました。これにより、各スキーマの出力先をより詳細に制御でき、各スキーマに固有の設定を適用することができます。

Redocly config

openapi-typescript を使用するには redocly.yaml ファイルは必須ではありません。デフォルトでは、組み込みの "minimal" 設定を拡張します。ただし、カスタム検証ルールや複数のスキーマの型を構築したい場合には使用をお勧めします。CLI はプロジェクトのルートディレクトリで redocly.yaml を自動的に見つけようとしますが、--redocly フラグを使用してその場所を指定することもできます：

npx openapi-typescript --redocly ./path/to/redocly.yaml

Redoclyの設定オプションについての詳細は Redoclyのドキュメントをご覧ください。

認証

非公開スキーマの認証は、Redocly configで処理します。次のようにヘッダーや基本認証を追加できます：

redocly.yaml

resolve:
  http:
    headers:
      - matches: https://api.example.com/v2/**
        name: X-API-KEY
        envVariable: SECRET_KEY
      - matches: https://example.com/*/test.yaml
        name: Authorization
        envVariable: SECRET_AUTH

その他のオプションについては、Redocly ドキュメントをご参照ください。

フラグ

CLI は以下のフラグをサポートしています：

フラグ	エイリアス	デフォルト	説明
--help			インラインヘルプメッセージを表示し終了します
--version			このライブラリのバージョンを表示し終了します
--output [location]	-o	(stdout)	出力ファイルを保存する場所を指定します
--redocly [location]			redocly.yaml ファイルへのパスを指定します (詳細は 複数スキーマ を参照)
--additional-properties		false	additionalProperties: false がないすべてのスキーマオブジェクトに任意のプロパティを許可します
--alphabetize		false	型をアルファベット順にソートします
--array-length		false	配列の minItems / maxItems を使用してタプルを生成します
--default-non-nullable		true	デフォルト値を持つスキーマオブジェクトを、非nullableとして扱います（parametersを除きます）
--properties-required-by-default		false	required がないスキーマオブジェクトについて、すべてのプロパティを必須として扱います
--empty-objects-unknown		false	指定されたプロパティも additionalProperties もないスキーマオブジェクトに任意のプロパティを許可します
--enum		false	文字列のユニオン型ではなく、TS enums を生成します
--enum-values		false	enumの値を配列としてエクスポートします
--dedupe-enums		false	--enum=true が設定されている場合、enumの重複を排除します
--check		false	生成された型が最新であることを確認します
--exclude-deprecated		false	型から廃止されたフィールドを除外します
--export-type	-t	false	interface の代わりに type をエクスポートします
--immutable		false	不変の型（readonlyプロパティおよびreadonly配列）を生成します
--path-params-as-types		false	paths オブジェクトで動的な文字列の参照を許可します
--root-types		false	components から型をルートレベルの型エイリアスとしてエクスポートする

pathParamsAsTypes

デフォルトでは、URL はスキーマに記載された通りに保持されます：

my-openapi-3-schema.d.ts

export interface paths {
  "/user/{user_id}": components["schemas"]["User"];
}

つまり、型の参照も正確な URL に一致する必要があります。

src/my-project.ts

import type { paths } from "./my-openapi-3-schema";

const url = `/user/${id}`;
type UserResponses = paths["/user/{user_id}"]["responses"];

しかし、--path-params-as-types オプションを有効にすると、次のように動的な参照を利用することができます。

src/my-project.ts

import type { paths } from "./my-openapi-3-schema";

const url = `/user/${id}`;
type UserResponses = paths[url]["responses"]; // 自動的に `paths['/user/{user_id}']` に一致します

これは人為的な例ですが、この機能を使用して、フェッチクライアントやアプリケーション内の他に有用的な場面で、URLに基づいて型を自動的に推論することができます。

ありがとう, @Powell-v2!

arrayLength

このオプションは、配列タイプが minItems または maxItems を指定している場合にタプルを生成するのに便利です。

例えば、以下のスキーマが与えられた場合:

my-openapi-3-schema.yaml

components:
  schemas:
    TupleType:
      type: array
      items:
        type: string
      minItems: 1
      maxItems: 2

--array-length を有効にすると、型が次のように変更されます:

my-openapi-3-schema.d.ts

export interface components {
  schemas: {
    TupleType: string[]; 
    TupleType: [string] | [string, string]; 
  };
}

これにより、配列の長さに対するより明示的な型チェックが可能になります。

注: この機能には合理的な制限があります。例えば maxItems: 100 の場合は、単純に string[]; に戻ります。

ありがとう, @kgtkr!