はじめに

Web開発においてはTypeScriptの採用率が高まっています。
私が担当している開発ではフロントエンドとバックエンド共にTypeScriptを採用していますが、その状況でフロントエンドとバックエンドで型定義を共有して安全な開発をしたいと思うのは当然の欲求だと思います。

本記事では、Swagger Editorを用いたOpenAPI仕様に則ったAPI仕様書を作成する方法と、openapi-typescriptを用いてTypeScript用の型定義ファイルを出力し、フロントエンドとバックエンド間で型安全な開発を実現する方法について解説します。

Swagger Editorを用いたAPI仕様書の記載方法

Swagger EditorはOpenAPI仕様に則ったAPI仕様を作成するためのツールです。
Webブラウザで利用できますが、IDEとしてVisual Studio Codeを用いている場合は拡張機能として提供されています。

Swagger Editorを使用すると、YAMLまたはJSON形式でAPI仕様書を作成することができます。
以下は簡単な例です。

sample_api.yml

openapi: 3.0.1
info:
  title: サンプル API
  version: 1.0.0
  description: API仕様書のサンプルです
paths:
  /users:
    get:
      summary: ユーザ一覧の取得
      responses:
        '200':
          description: ユーザ一覧
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: number
                    name:
                      type: string

openapi-typescriptを用いたTypeScript用の型定義ファイルの出力

openapi-typescriptは、OpenAPIスキーマをTypeScriptに変換するツールです。
これにより、OpenAPI仕様に則ったAPI仕様を元に型定義ファイルを自動生成し、フロントエンドとバックエンド間の型安全な開発を快適に進めることが可能になります。
以下は先にSwagger Editorで作成したsample_api.ymlをインプットとした例となります。

npx openapi-typescript ./api-schema/documents/sample_api.yml -o ./api-schema/src/schema.ts -t type --root-types

もしフロントエンドとバックエンド共にTypeScriptを採用する場合は、openapi-typescriptの採用を検討してみてください。