openapi-typescriptのCLIオプション、全部見る

はじめに

openapi-typescript は OpenAPI 3.0,3.1 のスキーマを TypeScript に変換するツールです。

以下のようにスキーマファイルのパスと出力ファイルのパスを指定することで、スキーマを TS に変換できます。

npx openapi-typescript ./path/to/my/schema.yaml -o ./path/to/my/schema.ts

CLI オプションというのは、上記例の「-o」のように、スキーマから TS に変換する際の振る舞いを制御できる仕組みです.
この記事では、openapi-typescript で使用できるオプションがどのようなものがあるかを見ていきます。

openapi-typescript(v7.1.0)時点の情報をもとに記事を書いています。

オプション一覧

出力に関するオプション

flag	alias	default	description
--output [location]	-o	(stdout)	出力ファイルを保存する場所を指定します
--alphabetize		false	型をアルファベット順にソートします

--output [location]

[location] (出力ファイル先) に生成した結果が出力されます。

generated.ts

/**
 * This file was auto-generated by openapi-typescript.
 * Do not make direct changes to the file.
 */
export interface paths { /* 実際の結果が入る */ }
export interface components { /* 実際の結果が入る */ }
export interface operations { /* 実際の結果が入る */ }
...

--alphabetize

型をアルファベット順にソートします

schema.yaml

components:
  schemas:
    Beta:
      type: object
      properties:
        b:
          type: boolean
        c:
          type: boolean
        a:
          type: boolean
    Alpha:
      type: object
      properties:
        z:
          type: boolean
        a:
          type: boolean
    Gamma:
      type: object
      properties:
        10:
          type: boolean
        2:
          type: boolean
        1:
          type: boolean

generated.ts

export interface components {
    schemas: {
        Alpha: {
            a?: boolean;
            z?: boolean;
        };
        Beta: {
            a?: boolean;
            b?: boolean;
            c?: boolean;
        };
        Gamma: {
            1?: boolean;
            2?: boolean;
            10?: boolean;
        };
    };

上の例から分かる通り、localeCompare で Numeric sortingするので numeric な key も昇順にソートします。

packages/openapi-typescript/src/lib/utils.ts

if (options?.alphabetize) {
  entries.sort(([a], [b]) => a.localeCompare(b, "en-us", { numeric: true }));
}

型の生成に関するオプション

flag	alias	default	description
--additional-properties		false	additionalProperties: false が指定されていない全てのスキーマオブジェクトに任意のプロパティを許可します
--default-non-nullable		true	default 値が設定されているスキーマオブジェクトを非 null として扱います（パラメータを除く）
--properties-required-by-default		false	required が指定されていないスキーマオブジェクトは全てのプロパティが必須であるとみなします
--empty-objects-unknown		false	プロパティが指定されておらず、additionalProperties も指定されていないスキーマオブジェクトに任意のプロパティを許可します
--enum		false	文字列のユニオンではなく、Enum を生成します
--enum-values		false	Enum の値を配列でエクスポートします
--export-type	-t	false	interfaceの代わりにtypeをエクスポートします
--immutable		false	immutable types を生成します（読み取り専用プロパティと読み取り専用配列）
--path-params-as-types		false	paths オブジェクトでスキーマに記載された静的な URL に一致させる必要がなくなり、URL に基づいた動的な型参照が可能になります
--array-length		false	配列の minItems / maxItems を使用してタプルを生成します
--exclude-deprecated		false	型から非推奨フィールドを除外します

--additional-properties

additionalProperties: false が指定されていない全てのスキーマオブジェクトに任意のプロパティを許可します

generated.ts (指定なし)

export interface components {
    schemas: {
        animal: {
            kind?: string;
        };
    };
}

generated.ts (指定あり)

export interface components {
    schemas: {
        animal: {
            kind?: string;
            [key: string]: unknown;
        };
    };
}

--default-non-nullable

default 値が設定されているスキーマオブジェクトを非 null として扱います（パラメータを除く）

generated.ts (false)

export interface components {
    schemas: {
        animal: {
            /** @default cat */
            kind?: string;
        };
    };
}

generated.ts (true)

export interface components {
    schemas: {
        animal: {
            /** @default cat */
            kind: string;
        };
    };
}

--properties-required-by-default

required が指定されていないスキーマオブジェクトは全てのプロパティが必須であるとみなします

generated.ts (指定なし)

export interface components {
    schemas: {
        animal: {
            id?: number;
            kind?: string;
        };
    };
}

generated.ts (指定あり)

export interface components {
    schemas: {
        animal: {
            id: number;
            kind: string;
        };
    };
}

--empty-objects-unknown

OpenAPI スキーマの空のオブジェクトに対する型の扱いが変わります。
プロパティが指定されておらず、additionalProperties も指定されていないスキーマオブジェクトに任意のプロパティを許可します。

schema.yaml

components:
  schemas:
    EmptyObject:
      type: object  # プロパティが存在しない

generated.ts (指定なし)

export interface components {
    schemas: {
        EmptyObject: Record<string, never>;
    };
}

generated.ts (指定あり)

export interface components {
    schemas: {
        EmptyObject: Record<string, unknown>;
    };
}

--enum

文字列のユニオンではなく、Enum を生成します

generated.ts (指定なし)

export interface components {
    schemas: {
        animal: {
            /** @enum {string} */
            kind?: "dog" | "cat";
        };
    };

generated.ts (指定あり)

export interface components {
    schemas: {
        animal: {
            /** @enum {string} */
            kind?: AnimalKind;
        };
    };
}

export enum AnimalKind {
    dog = "dog",
    cat = "cat"
}

--enum-values

Enum の値を配列でエクスポートします

generated.ts (指定あり)

export const animalKindValues: ReadonlyArray<
  components["schemas"]["animal"]["kind"]
> = ["dog", "cat"];

--export-type

interfaceの代わりにtypeをエクスポートします

generated.ts (指定なし)

export interface components { ... }

generated.ts (指定あり)

export type components = { ... }

--immutable

immutable types を生成します（読み取り専用プロパティと読み取り専用配列）

generated.ts (指定なし)

export interface components {
    a: string;
    b: string;
}

generated.ts (指定あり)

export interface components {
  readonly a: string;
  readonly b: string;
}

--path-params-as-types

公式ドキュメントに詳細があるので省略します。
https://openapi-ts.dev/cli#pathparamsastypes

--array-length

公式ドキュメントに詳細があるので省略します。
https://openapi-ts.dev/cli#arraylength

--exclude-deprecated

型から非推奨フィールドを除外します

schema.yaml

schemas:
    Alpha:
        type: object
        properties:
        a:
            type: boolean
            deprecated: true
        z:
            type: boolean

generated.ts

schemas: {
    Alpha: {
        z?: boolean;
    };
};

その他のオプション

flag	alias	default	description
--help			ヘルプメッセージを表示して終了します
--version			ライブラリのバージョンを表示して終了します
--check		false	生成された型が最新であることを確認します
--redocly [location]			redocly.yaml ファイルのパスを指定します

--help

以下の通り ヘルプ情報（Usage と Options） が表示されます。

output

Usage
  $ openapi-typescript [input] [options]

Options
  --help                     Display this
  --version                  Display the version
  --redocly [path], -c       Specify path to Redocly config (default: redocly.yaml)
  --output, -o               Specify output file (if not specified in redocly.yaml)
  --enum                     Export true TS enums instead of unions
  --enum-values              Export enum values as arrays
  --check                    Check that the generated types are up-to-date. (default: false)
  --export-type, -t          Export top-level `type` instead of `interface`
  --immutable                Generate readonly types
  --additional-properties    Treat schema objects as if `additionalProperties: true` is set
  --empty-objects-unknown    Generate `unknown` instead of `Record<string, never>` for empty objects
  --default-non-nullable     Set to `false` to ignore default values when generating non-nullable types
  --properties-required-by-default
                             Treat schema objects as if `required` is set to all properties by default
  --array-length             Generate tuples using array minItems / maxItems
  --path-params-as-types     Convert paths to template literal types
  --alphabetize              Sort object keys alphabetically
  --exclude-deprecated       Exclude deprecated types

--version

使用している openapi-typescript のバージョンが表示されます。

output

v7.1.0

--check

生成された型が最新であることを確認します。最新でない場合は、以下のようにエラーが表示されます。

output

 ✘  Generated types are not up-to-date!

--redocly [location]

redocly.yaml ファイルのパスを指定します。

おわりに

筆者は基本的にはデフォルトのまま使用することが多いですが、こうしてみると色々なオプションがあることを再確認できました。何かの参考になれば嬉しいです。