【TypeScript】SwaggerからのAPI型自動生成 - 型安全なAPI開発を効率化

SwaggerとAPI型自動生成の概要

Swaggerは、APIの設計やドキュメントの作成をサポートするオープンソースのフレームワークで、OpenAPIという仕様に基づいたAPI定義フォーマットを提供しています。Swaggerによって、APIエンドポイントの構造やデータ形式を詳細に記述することができ、ドキュメントとしても利用可能です。
TypeScriptを用いたAPI開発では、Swaggerを使って記述されたAPI仕様から型を自動生成することで、型安全なAPI呼び出しが可能となり、フロントエンドとバックエンドのデータ形式の整合性を維持しやすくなります。

Swaggerからの型自動生成の利点

• コンパイル時に型チェックが可能
  自動生成された型を使用することで、APIレスポンスやリクエストのデータ型が確実に一致し、コンパイル時にエラーを検出できます。
• 開発効率の向上
  フロントエンド開発者がSwagger仕様に基づく正確な型情報を直接利用できるため、バックエンドの変更に追従しやすく、修正箇所が減少します。
• 保守性とドキュメントとしての活用
  Swaggerの定義はドキュメントとしても利用できるため、バックエンドの仕様変更を容易に管理でき、フロントエンド開発者とバックエンド開発者の連携が向上します。

TypeScriptでSwaggerからAPI型を自動生成する手順

SwaggerのAPI仕様を確認

まず、SwaggerのAPI仕様（OpenAPI Specification）がJSONまたはYAML形式で記述されていることを確認します。以下はその一例です。

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get user list
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

このAPI仕様では、ユーザーのリストを返すエンドポイント/usersが定義されています。

型自動生成ツールの導入

Swagger仕様から型を自動生成するには、openapi-typescript-codegenやswagger-typescript-apiといったツールが便利です。ここではopenapi-typescript-codegenを使用します。

インストール

以下のコマンドでopenapi-typescript-codegenをインストールします。

npm install openapi-typescript-codegen --save-dev

TypeScript型の自動生成

インストールが完了したら、Swaggerの仕様からTypeScript型を生成します。API仕様のURLやファイルパスを指定して型を生成できます。

npx openapi-typescript-codegen --input ./path/to/swagger.yaml --output ./src/api

上記コマンドで、Swagger仕様に基づくTypeScriptファイルがsrc/apiに生成されます。このファイルには、各エンドポイントに対応したリクエストやレスポンスの型が含まれます。

自動生成された型を使ったAPI呼び出し

生成された型定義を使い、TypeScriptで型安全なAPI呼び出しを実装します。以下は、自動生成された型を用いた例です。

import { UserApi } from './api/apis/UserApi';
import { Configuration } from './api';
const config = new Configuration({ basePath: 'http://localhost:3000' });
const userApi = new UserApi(config);
async function fetchUsers() {
  try {
    const response = await userApi.getUsers();
    response.data.forEach(user => {
      console.log(`User ID: ${user.id}, Name: ${user.name}`);
    });
  } catch (error) {
    console.error('API call failed:', error);
  }
}

上記のコードでは、UserApiクラスを用いてユーザーリストを取得しています。自動生成された型情報により、APIレスポンス内のデータ構造が確実に一致しているか、コンパイル時にチェックされます。

型自動生成のメリットと注意点

型自動生成によるメリットは大きいですが、いくつかの注意点もあります。

• API仕様の変更に追従が必要
  Swagger仕様が変更された場合、型を再生成する必要があります。CI/CDパイプラインに型生成を組み込むことで、常に最新の型定義が利用可能です。
• 生成ファイルの保守
  自動生成されたファイルは、通常手動で編集しません。仕様変更時はSwagger定義の更新を行い、再生成によって型定義を最新化します。

まとめ

Swagger仕様からTypeScriptのAPI型を自動生成することで、型安全なAPI開発が可能となり、開発効率や保守性が向上します。openapi-typescript-codegenのようなツールを使用して、Swaggerから自動生成された型を活用することで、フロントエンドとバックエンドのデータ形式の整合性を保ちながら、信頼性の高いAPI開発が実現できます。TypeScriptの強力な型システムを取り入れることで、API開発の生産性と品質をさらに向上させましょう。