OpenAPI to TypeScript

OpenAPI 3.0 スペシフィケーションをTypeScriptインターフェースと型ガードに変換します。

入力: OpenAPIファイル (JSON または YAML) 出力: インターフェースと型ガードを含むTypeScriptファイル

使用場面

• "openapi から型を生成"
• "openapi を typescript に変換"
• "API インターフェースを作成"
• "スペックから型を生成"

ワークフロー

1. OpenAPIファイルパスをリクエスト (提供されていない場合)
2. ファイルを読み込んで検証 (OpenAPI 3.0.x である必要があります)
3. components/schemas からスキーマを抽出
4. paths からエンドポイントを抽出 (リクエスト/レスポンス型)
5. TypeScript を生成 (インターフェース + 型ガード)
6. 保存先をリクエスト (デフォルト: 現在のディレクトリの types/api.ts)
7. ファイルを書き込む

OpenAPI検証

処理前に確認する項目:

- フィールド "openapi" は存在し、"3.0" で始まる必要があります
- フィールド "paths" は存在する必要があります
- フィールド "components.schemas" は存在する必要があります (型がある場合)

無効な場合、エラーを報告して処理を中止します。

型マッピング

プリミティブ型

OpenAPI	TypeScript
string	string
number	number
integer	number
boolean	boolean
null	null

フォーマット修飾子

フォーマット	TypeScript
uuid	string (UUID コメント付き)
date	string (日付 コメント付き)
date-time	string (ISO コメント付き)
email	string (メール コメント付き)
uri	string (URI コメント付き)

複雑な型

オブジェクト:

// OpenAPI: type: object, properties: {id, name}, required: [id]
interface Example {
  id: string;      // 必須: ? なし
  name?: string;   // オプション: ? あり
}

配列:

// OpenAPI: type: array, items: {type: string}
type Names = string[];

列挙型:

// OpenAPI: type: string, enum: [active, draft]
type Status = "active" | "draft";

oneOf (ユニオン):

// OpenAPI: oneOf: [{$ref: Cat}, {$ref: Dog}]
type Pet = Cat | Dog;

allOf (交差/継承):

// OpenAPI: allOf: [{$ref: Base}, {type: object, properties: ...}]
interface Extended extends Base {
  extraField: string;
}

コード生成

ファイルヘッダー

/**
 * Auto-generated from: {source_file}
 * Generated at: {timestamp}
 *
 * DO NOT EDIT MANUALLY - Regenerate from OpenAPI schema
 */

インターフェース (components/schemas から)

components/schemas の各スキーマに対して:

export interface Product {
  /** Product unique identifier */
  id: string;

  /** Product title */
  title: string;

  /** Product price */
  price: number;

  /** Created timestamp */
  created_at?: string;
}

• OpenAPI の description を JSDoc として使用
• required[] 内のフィールドは ? なし
• required[] 外のフィールドは ? あり

リクエスト/レスポンス型 (paths から)

paths の各エンドポイントに対して:

// GET /products - クエリパラメータ
export interface GetProductsRequest {
  page?: number;
  limit?: number;
}

// GET /products - レスポンス 200
export type GetProductsResponse = ProductList;

// POST /products - リクエストボディ
export interface CreateProductRequest {
  title: string;
  price: number;
}

// POST /products - レスポンス 201
export type CreateProductResponse = Product;

命名規則:

• パラメータ/ボディ: {Method}{Path}Request
• レスポンス: {Method}{Path}Response

型ガード

各メインインターフェースに対して、型ガードを生成:

export function isProduct(value: unknown): value is Product {
  return (
    typeof value === 'object' &&
    value !== null &&
    'id' in value &&
    typeof (value as any).id === 'string' &&
    'title' in value &&
    typeof (value as any).title === 'string' &&
    'price' in value &&
    typeof (value as any).price === 'number'
  );
}

型ガードのルール:

• typeof value === 'object' && value !== null をチェック
• 各必須フィールド: 'field' in value をチェック
• プリミティブフィールド: typeof をチェック
• 配列: Array.isArray() をチェック
• 列挙型: .includes() をチェック

エラー型 (常に含める)

export interface ApiError {
  status: number;
  error: string;
  detail?: string;
}

export function isApiError(value: unknown): value is ApiError {
  return (
    typeof value === 'object' &&
    value !== null &&
    'status' in value &&
    typeof (value as any).status === 'number' &&
    'error' in value &&
    typeof (value as any).error === 'string'
  );
}

$ref の解決

{"$ref": "#/components/schemas/Product"} に遭遇した場合:

1. スキーマ名を抽出 (Product)
2. 型を直接使用 (インラインで解決しない)

// OpenAPI: items: {$ref: "#/components/schemas/Product"}
// TypeScript:
items: Product[]  // 参照、インラインではない

完全な例

入力 (OpenAPI):

{
  "openapi": "3.0.0",
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": {"type": "string", "format": "uuid"},
          "email": {"type": "string", "format": "email"},
          "role": {"type": "string", "enum": ["admin", "user"]}
        },
        "required": ["id", "email", "role"]
      }
    }
  },
  "paths": {
    "/users/{id}": {
      "get": {
        "parameters": [{"name": "id", "in": "path", "required": true}],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/User"}
              }
            }
          }
        }
      }
    }
  }
}

出力 (TypeScript):

/**
 * Auto-generated from: api.openapi.json
 * Generated at: 2025-01-15T10:30:00Z
 *
 * DO NOT EDIT MANUALLY - Regenerate from OpenAPI schema
 */

// ============================================================================
// Types
// ============================================================================

export type UserRole = "admin" | "user";

export interface User {
  /** UUID */
  id: string;

  /** Email */
  email: string;

  role: UserRole;
}

// ============================================================================
// Request/Response Types
// ============================================================================

export interface GetUserByIdRequest {
  id: string;
}

export type GetUserByIdResponse = User;

// ============================================================================
// Type Guards
// ============================================================================

export function isUser(value: unknown): value is User {
  return (
    typeof value === 'object' &&
    value !== null &&
    'id' in value &&
    typeof (value as any).id === 'string' &&
    'email' in value &&
    typeof (value as any).email === 'string' &&
    'role' in value &&
    ['admin', 'user'].includes((value as any).role)
  );
}

// ============================================================================
// Error Types
// ============================================================================

export interface ApiError {
  status: number;
  error: string;
  detail?: string;
}

export function isApiError(value: unknown): value is ApiError {
  return (
    typeof value === 'object' &&
    value !== null &&
    'status' in value &&
    typeof (value as any).status === 'number' &&
    'error' in value &&
    typeof (value as any).error === 'string'
  );
}

よくあるエラー

エラー	対応
OpenAPI バージョン != 3.0.x	3.0 のみサポートされていることを報告
$ref が見つからない	見つからない参照をリストアップ
不明な型	unknown を使用し警告
循環参照	型エイリアスと遅延参照を使用