その手の平は尻もつかめるさ

ギジュツ的な事をメーンで書く予定です

openapi-fetch-genを作った

TypeScript OpenAPI

English article is here: openapi-fetch-gen – Generate TypeScript API client from OpenAPI TypeScript interface definitions created by openapi-typescript - DEV Community

npm registryにも公開されています。

従って以下のようにダウンロード可能です。

npm install @moznion/openapi-fetch-gen

これは何 / 背景

OpenAPI 3の仕様からopenapi-ts/openapi-typescriptにより生成されたスキーマ (.d.ts) ファイルからTypeScriptのAPIクライアントを自動生成するツールです。

openapi-ts/openapi-typescriptはかなりパワフルかつ完成度が高いツールで、比較的複雑なOpenAPIの定義からでも綺麗なスキーマファイルを生成することができます。なおかつopenapi-fetchというライブラリも併せて提供されており、これを用いることで生成されたスキーマファイルと組み合わせてAPI Clientをtype-safeな形で作成することができます。

ただこれには1点課題があり、openapi-fetchはあくまで「スキーマを読み込んでAPI Clientが作れるライブラリ」であり「APIクライアントを自動生成するものではない」ため、各エンドポイントについてAPIクライアントをマニュアルで作成する必要がありました。

という課題を解決するためにこの度作成されたのがこのopenapi-fetch-genです。

用法

以下のようなOpenAPI 3の定義YAMLを例に取ります。


schema.yaml (ちょっと長いですが、まあよくあるREST APIの定義だと思ってください)

openapi: 3.0.3
info:
  title: Fictional Library User Management Service API
  version: 1.0.0
  description: |
    A RESTful API for managing library user records and their loan information.
servers:
  - url: https://api.fictionallibrary.example.com/v1
    description: Production server

paths:
  /users/{userId}:
    parameters:
      - $ref: '#/components/parameters/userId'
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Authorization Header
      - name: Application-Version
        in: header
        required: true
        schema:
          type: string
        description: Application version
      - name: Something-Id
        in: header
        required: true
        schema:
          type: string
        description: Identifier of something
    get:
      summary: Get user details
      description: Retrieve detailed information for a specific user.
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      summary: Replace user
      description: Replace a user's entire record.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
      responses:
        '200':
          description: Updated user record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      summary: Update user fields
      description: Partially update a user's information.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserPatch'
      responses:
        '200':
          description: Updated user record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      summary: Delete user
      description: Soft-delete a user record.
      responses:
        '204':
          description: User deleted (no content)
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

components:
  parameters:
    userId:
      name: userId
      in: path
      required: true
      description: Unique user identifier (UUID)
      schema:
        type: string
        format: uuid

  responses:
    BadRequest:
      description: Bad request due to invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication required or failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Insufficient permissions to access resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Conflict with current state of the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    Error:
      type: object
      properties:
        code:
          type: integer
          description: HTTP status code
        message:
          type: string
          description: Error message detailing the cause
      required:
        - code
        - message

    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type: string
          format: email
        membershipType:
          type: string
          enum: [REGULAR, PREMIUM, STUDENT]
        registeredAt:
          type: string
          format: date-time
        address:
          $ref: '#/components/schemas/Address'
      required:
        - id
        - name
        - email
        - membershipType
        - registeredAt

    Address:
      type: object
      properties:
        postalCode:
          type: string
        street:
          type: string
        city:
          type: string
        country:
          type: string
      required:
        - street
        - city
        - country

    UserCreate:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        membershipType:
          type: string
          enum: [REGULAR, PREMIUM, STUDENT]
        address:
          $ref: '#/components/schemas/Address'
      required:
        - name
        - email
        - membershipType

    UserUpdate:
      allOf:
        - $ref: '#/components/schemas/UserCreate'
        - type: object
          properties:
            id:
              type: string
              format: uuid
          required:
            - id

    UserPatch:
      type: object
      description: Schema for partial updates – include only fields to change
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        membershipType:
          type: string
          enum: [REGULAR, PREMIUM, STUDENT]
        address:
          $ref: '#/components/schemas/Address'

この時に以下のようなコマンドを実行するとopenapi-typescriptを用いてスキーマファイル (.d.ts) が生成されます:

openapi-typescript --output schema.d.ts ./schema.yaml

この時に生成されるスキーマファイルは以下のようになっています


schema.d.ts

/**
 * This file was auto-generated by openapi-typescript.
 * Do not make direct changes to the file.
 */

export interface paths {
    "/users/{userId}": {
        parameters: {
            query?: never;
            header: {
                /** @description Authorization Header */
                Authorization: string;
                /** @description Application version */
                "Application-Version": string;
                /** @description Identifier of something */
                "Something-Id": string;
            };
            path: {
                /** @description Unique user identifier (UUID) */
                userId: components["parameters"]["userId"];
            };
            cookie?: never;
        };
        /**
         * Get user details
         * @description Retrieve detailed information for a specific user.
         */
        get: {
            parameters: {
                query?: never;
                header: {
                    /** @description Authorization Header */
                    Authorization: string;
                    /** @description Application version */
                    "Application-Version": string;
                    /** @description Identifier of something */
                    "Something-Id": string;
                };
                path: {
                    /** @description Unique user identifier (UUID) */
                    userId: components["parameters"]["userId"];
                };
                cookie?: never;
            };
            requestBody?: never;
            responses: {
                /** @description User details */
                200: {
                    headers: {
                        [name: string]: unknown;
                    };
                    content: {
                        "application/json": components["schemas"]["User"];
                    };
                };
                400: components["responses"]["BadRequest"];
                401: components["responses"]["Unauthorized"];
                403: components["responses"]["Forbidden"];
                404: components["responses"]["NotFound"];
            };
        };
        /**
         * Replace user
         * @description Replace a user's entire record.
         */
        put: {
            parameters: {
                query?: never;
                header: {
                    /** @description Authorization Header */
                    Authorization: string;
                    /** @description Application version */
                    "Application-Version": string;
                    /** @description Identifier of something */
                    "Something-Id": string;
                };
                path: {
                    /** @description Unique user identifier (UUID) */
                    userId: components["parameters"]["userId"];
                };
                cookie?: never;
            };
            requestBody: {
                content: {
                    "application/json": components["schemas"]["UserUpdate"];
                };
            };
            responses: {
                /** @description Updated user record */
                200: {
                    headers: {
                        [name: string]: unknown;
                    };
                    content: {
                        "application/json": components["schemas"]["User"];
                    };
                };
                400: components["responses"]["BadRequest"];
                401: components["responses"]["Unauthorized"];
                403: components["responses"]["Forbidden"];
                404: components["responses"]["NotFound"];
            };
        };
        post?: never;
        /**
         * Delete user
         * @description Soft-delete a user record.
         */
        delete: {
            parameters: {
                query?: never;
                header: {
                    /** @description Authorization Header */
                    Authorization: string;
                    /** @description Application version */
                    "Application-Version": string;
                    /** @description Identifier of something */
                    "Something-Id": string;
                };
                path: {
                    /** @description Unique user identifier (UUID) */
                    userId: components["parameters"]["userId"];
                };
                cookie?: never;
            };
            requestBody?: never;
            responses: {
                /** @description User deleted (no content) */
                204: {
                    headers: {
                        [name: string]: unknown;
                    };
                    content?: never;
                };
                400: components["responses"]["BadRequest"];
                401: components["responses"]["Unauthorized"];
                403: components["responses"]["Forbidden"];
                404: components["responses"]["NotFound"];
            };
        };
        options?: never;
        head?: never;
        /**
         * Update user fields
         * @description Partially update a user's information.
         */
        patch: {
            parameters: {
                query?: never;
                header: {
                    /** @description Authorization Header */
                    Authorization: string;
                    /** @description Application version */
                    "Application-Version": string;
                    /** @description Identifier of something */
                    "Something-Id": string;
                };
                path: {
                    /** @description Unique user identifier (UUID) */
                    userId: components["parameters"]["userId"];
                };
                cookie?: never;
            };
            requestBody: {
                content: {
                    "application/json": components["schemas"]["UserPatch"];
                };
            };
            responses: {
                /** @description Updated user record */
                200: {
                    headers: {
                        [name: string]: unknown;
                    };
                    content: {
                        "application/json": components["schemas"]["User"];
                    };
                };
                400: components["responses"]["BadRequest"];
                401: components["responses"]["Unauthorized"];
                403: components["responses"]["Forbidden"];
                404: components["responses"]["NotFound"];
            };
        };
        trace?: never;
    };
}
export type webhooks = Record<string, never>;
export interface components {
    schemas: {
        Error: {
            /** @description HTTP status code */
            code: number;
            /** @description Error message detailing the cause */
            message: string;
        };
        User: {
            /** Format: uuid */
            id: string;
            name: string;
            /** Format: email */
            email: string;
            /** @enum {string} */
            membershipType: "REGULAR" | "PREMIUM" | "STUDENT";
            /** Format: date-time */
            registeredAt: string;
            address?: components["schemas"]["Address"];
        };
        Address: {
            postalCode?: string;
            street: string;
            city: string;
            country: string;
        };
        UserCreate: {
            name: string;
            /** Format: email */
            email: string;
            /** @enum {string} */
            membershipType: "REGULAR" | "PREMIUM" | "STUDENT";
            address?: components["schemas"]["Address"];
        };
        UserUpdate: components["schemas"]["UserCreate"] & {
            /** Format: uuid */
            id: string;
        };
        /** @description Schema for partial updates – include only fields to change */
        UserPatch: {
            name?: string;
            /** Format: email */
            email?: string;
            /** @enum {string} */
            membershipType?: "REGULAR" | "PREMIUM" | "STUDENT";
            address?: components["schemas"]["Address"];
        };
    };
    responses: {
        /** @description Bad request due to invalid input */
        BadRequest: {
            headers: {
                [name: string]: unknown;
            };
            content: {
                "application/json": components["schemas"]["Error"];
            };
        };
        /** @description Authentication required or failed */
        Unauthorized: {
            headers: {
                [name: string]: unknown;
            };
            content: {
                "application/json": components["schemas"]["Error"];
            };
        };
        /** @description Insufficient permissions to access resource */
        Forbidden: {
            headers: {
                [name: string]: unknown;
            };
            content: {
                "application/json": components["schemas"]["Error"];
            };
        };
        /** @description Resource not found */
        NotFound: {
            headers: {
                [name: string]: unknown;
            };
            content: {
                "application/json": components["schemas"]["Error"];
            };
        };
        /** @description Conflict with current state of the resource */
        Conflict: {
            headers: {
                [name: string]: unknown;
            };
            content: {
                "application/json": components["schemas"]["Error"];
            };
        };
    };
    parameters: {
        /** @description Unique user identifier (UUID) */
        userId: string;
    };
    requestBodies: never;
    headers: never;
    pathItems: never;
}
export type $defs = Record<string, never>;
export type operations = Record<string, never>;

これまでは、この生成されたスキーマファイルとopenapi-fetchを併用して手でAPIクライアントを書く必要がありましたが、openapi-fetch-genを使うとスキーマファイルを入力として以下のように実行することでAPIクライアントを自動生成することができます:

openapi-fetch-gen --input ./schema.d.ts --output ./generated_client.ts

generated_client.tsはschema.d.tsを元に自動生成されたTypeScriptレベルでtype-safeなAPIクライアントです。一部を抽出すると以下のようなコードとなります:

import createClient, { type ClientOptions } from "openapi-fetch";
import type { paths } from "./schema"; // generated by openapi-typescript

export class Client {
  private readonly client;

  constructor(clientOptions: ClientOptions) {
    this.client = createClient<paths>(clientOptions);
  }

  ...

  /**
   * Replace user
   */
  async putUsersUserid(
    params: {
      header: {
        Authorization: string;
        "Application-Version": string;
        "Something-Id": string;
      };
      path: { userId: string };
    },
    body: {
      name: string;
      email: string;
      membershipType: "REGULAR" | "PREMIUM" | "STUDENT";
      address?: {
        postalCode?: string;
        street: string;
        city: string;
        country: string;
      };
    } & { id: string },
  ) {
    return await this.client.PUT("/users/{userId}", {
      params,
      body,
    });
  }
  ...
}


FYI: 生成されるAPIクライアント (フル) 

// THIS FILE IS AUTO-GENERATED BY openapi-fetch-gen.
// DO NOT EDIT THIS FILE MANUALLY.
// See Also: https://github.com/moznion/openapi-fetch-gen
import createClient, { type ClientOptions } from "openapi-fetch";
import type { paths } from "./schema"; // generated by openapi-typescript

export class Client {
  private readonly client;

  constructor(clientOptions: ClientOptions) {
    this.client = createClient<paths>(clientOptions);
  }

  /**
   * Get user details
   */
  async getUsersUserid(params: {
    header: {
      Authorization: string;
      "Application-Version": string;
      "Something-Id": string;
    };
    path: { userId: string };
  }) {
    return await this.client.GET("/users/{userId}", {
      params,
    });
  }

  /**
   * Replace user
   */
  async putUsersUserid(
    params: {
      header: {
        Authorization: string;
        "Application-Version": string;
        "Something-Id": string;
      };
      path: { userId: string };
    },
    body: {
      name: string;
      email: string;
      membershipType: "REGULAR" | "PREMIUM" | "STUDENT";
      address?: {
        postalCode?: string;
        street: string;
        city: string;
        country: string;
      };
    } & { id: string },
  ) {
    return await this.client.PUT("/users/{userId}", {
      params,
      body,
    });
  }

  /**
   * Delete user
   */
  async deleteUsersUserid(params: {
    header: {
      Authorization: string;
      "Application-Version": string;
      "Something-Id": string;
    };
    path: { userId: string };
  }) {
    return await this.client.DELETE("/users/{userId}", {
      params,
    });
  }

  /**
   * Update user fields
   */
  async patchUsersUserid(
    params: {
      header: {
        Authorization: string;
        "Application-Version": string;
        "Something-Id": string;
      };
      path: { userId: string };
    },
    body: {
      name?: string;
      email?: string;
      membershipType?: "REGULAR" | "PREMIUM" | "STUDENT";
      address?: {
        postalCode?: string;
        street: string;
        city: string;
        country: string;
      };
    },
  ) {
    return await this.client.PATCH("/users/{userId}", {
      params,
      body,
    });
  }
}

なかなか便利なのではないでしょうか。

中身としてはどうなっているのか

TypeScript Compiler APIをdsherret/ts-morphライブラリを介して利用することで d.ts ファイルを解釈し、その内容・構造に基いてAPIクライアントコードを生成しています。また、上記の例のように生成されるAPIクライアントのコードの中ではopenapi-fetchが用いられています。

まとめ

というわけで、openapi-typescriptが出力するTypeScriptのスキーマからTypeScriptのAPIクライアントを自動生成するツールであるopenapi-fetch-genのご紹介でした。どうぞご利用ください。

ところで、これに加えて "Default HTTP Header" 機能というものも用意しており、これは本来の生成クライアントコードが要求してくる「APIエンドポイントを呼び出すメソッドそれぞれに明示的にHTTP Headerを渡さなければならない *1」というものを省力化するものです。良くある例としては、 Authorization ヘッダなんかはほとんどのエンドポイントで共通して渡す必要があったりしますが、これをすべてのAPIメソッド呼び出しメソッドで渡さなければならないとなると面倒ですよね。というわけでopenapi-fetch-genではジェネリクスを活用することでデフォルトのヘッダを渡せるようにしており、加えてちょっとしたTypeScriptの型のテクニックを内部的に使うことで、デフォルトヘッダとして指定されたヘッダを各API呼び出しメソッドで省略できるようにしています。
興味のある方はDefault HTTP Headersのセクションをご参照ください。

*1:上記の生成コード例におけるメソッドの引数中のparams.headerがそれに当たります