OpenAPIで始める快適なAPI設計（実践編）

はじめに

前回の記事では、OpenAPIの基本的な役割や構造について解説しました。

今回は、OpenAPIの定義ファイル（YAML）を元に、以下のような実践的な活用方法を紹介します。

• ドキュメントを見やすく自動生成する
• フロントエンドのAPI呼び出しコードを自動生成する
• 実務での効率化のポイント

Swagger UIでAPIドキュメントを自動生成

OpenAPIで記述されたYAMLファイルは、そのままインタラクティブなAPIドキュメントとして表示できます。

Swagger UIとは？

Swagger UIは、OpenAPIファイルをWeb上で視覚的に表示できるツールです。
APIエンドポイントやリクエスト内容** Try it Out **ボタンで実行確認もできるため、開発者やテスト時に非常に便利です。

ローカルにswagger-uiを配置し、YAMLファイルおw読み込むだけで使えます。
もしくは、Swagger EditorにYAMLをコピペするだけでもドキュメントが確認できます。

orvalでTypeScriptのクライアントコードを生成

orvalは、OpenAPI定義からTypeScriptのAPI呼び出しコードを自動生成するツールです。
ReactやNext.jsなどのフロントエンド開発と非常に相性がよく、Axiosベースのコードが生成されます。

✅インストール方法

npm install orval --save-dev

✅設定ファイル（orval.config.js）

module.exports = {
  petStore: {
    input: './openapi.yaml',
    output: {
      mode: 'tags-split',
      target: './src/api/generated/',
      client: 'axios',
    },
  },
}

✅実行コマンド

npx orval

これで、API呼び出し関数が/src/api/generatedに自動で生成されます。
React Query対応のhooksも生成されるため、開発速度が大幅に向上します。

実務で感じたメリット　・ 注意点

👍 メリット

• フロントエンドとバックエンドの認識ズレが激減
• 保守性が高く、仕様変更にも強い
• 手書きコードのバグが減る

⚠️注意点

• YAMLの構造が崩れるとツールが動かない
• ドキュメント／実装の同期は引き続き重要
• 自動生成コードに依存しすぎると柔軟性が下がることも

まとめ

OpenAPIをうまく活用すれば、APIの設計・実装・フロント連携までが一本の線でつながります。Swagger UIやorvalなどのツールを組み合わせることで、「手戻りのないAPI開発」を現実にすることができます。