こんにちは！日々のAPI開発、お疲れ様です。
突然ですが、皆さん、APIを作るときにこんなストレスを感じたことはありませんか？
「コードを書き進めたはいいものの、仕様書（ドキュメント）の更新を忘れて古い情報のまま放置されている……」
「フロントエンドのメンバーから『このAPIのレスポンス、本当にこの型で返ってくるの？』と何度もチャットで聞かれる……」
もし心当たりがあるなら、今日から「API仕様先行開発（Design-First）」の世界へ足を踏み入れてみませんか？
今回ご紹介するのは、APIクライアントとして絶大な支持を集める「Insomnia」の秘められた超重要機能、「デザインモード（Design Tab）」です。これさえ使いこなせば、OpenAPI（旧Swagger）を使った美しい仕様書の作成と、テスト可能なモックサーバーの立ち上げが、驚くほど爆速で完了します。
「OpenAPIとかYAMLとか、なんだか難しそう……」と思ったそこのあなた、大丈夫です。私と一緒に、基礎から一歩ずつ紐解いていきましょう。これをマスターすれば、あなたの毎日の開発作業は劇的に楽になりますよ！
—
1. なぜInsomniaの「デザインモード」なのか？
API開発のスタイルには、大きく分けて「コード先行（Code-First）」と「仕様先行（Design-First）」があります。
- コード先行の罠: 最初にプログラムを書き始めるため、仕様が曖昧なまま実装が進みやすく、ドキュメント作成が後回し（あるいは形骸化）になりがちです。
- 仕様先行の強み: まず「APIの設計図（OpenAPI）」を書き、それをチーム全員（フロントエンド、バックエンド、クライアント）で合意してから実装に入ります。
ここで登場するのが Insomnia です。通常、Insomniaは「APIを叩いてテストするツール（Debugタブ）」として使われますが、実は「OpenAPIの記述・リアルタイムプレビュー・モックサーバー生成」を一撃で行えるデザイン機能（Designタブ）を標準搭載しています。
わざわざ重い専用エディタを立ち上げたり、複雑なプレビュー環境を構築する必要はありません。Insomnia一つ開けば、設計からデバッグまでがシームレスに完結するのです。これが、現場のエンジニアにとって最高に心地よい体験をもたらしてくれます。
—
2. 5分で完了！Insomniaのインストールと初期準備
まずは環境を整えましょう。すでにInsomniaがインストールされている方は、このセクションはスキップして構いません。
1. ダウンロード: 公式サイト（[Insomnia公式サイト](https://insomnia.rest/)）から、お使いのOS（Mac / Windows / Linux）に合わせたインストーラーをダウンロードし、インストールします。
2. アカウント作成（またはスキップ）: 初回起動時にログイン画面が表示されます。チームでの共有機能をフルに使いたい場合はアカウントを作成しますが、まずはローカルで試したい場合はスキップやゲスト利用も可能です。
最初のプロジェクト（Design Document）の作り方
Insomniaを起動したら、以下の手順で「デザイン専用のワークスペース」を作成します。
1. 画面左上のドロップダウン、または「Create」ボタンをクリック。
2. 「Design Document」を選択します。（※通常の「Request Collection」ではない点に注意してください！）
3. 適度な名前（例: `User Management API`）を入力して作成します。
画面上部に 「Design」「Debug」「Metrics」 という3つのタブが現れましたか？
左端の「Design」こそが、今回の主役です。クリックしてみましょう！
—
3. 【実践】OpenAPIで「HelloWorld」仕様書を書いてみよう
デザインタブを開くと、画面が左右に分かれているはずです。
- 左側: OpenAPI（YAML形式）を記述するエディタ
- 右側: 記述した内容からリアルタイムに生成される美しいAPI仕様書プレビュー
ここに、最小限の「Hello World」を返すAPIの設計図を書いてみましょう。以下のコードを、左側のエディタに丸ごとコピー＆ペーストしてみてください。
丁寧なコメント付き：HelloWorldのOpenAPI（YAML）
openapi: 3.0.3
info:
title: 挨拶API (Hello World)
description: Insomniaのデザインモードの威力を知るための最初のステップです。
version: 1.0.0
servers:
- url: http://localhost:4010
description: ローカルモックサーバー
paths:
/hello:
get:
summary: 挨拶を返す
description: 「Hello, World!」というメッセージと現在時刻をJSON形式で返却します。
responses:
‘200’:
description: 成功時のレスポンス
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: “Hello, Insomnia Design Mode!”
timestamp:
type: string
format: date-time
example: “2026-03-30T12:00:00Z”
—
4. 画面を見て感動しよう！リアルタイムプレビューとモックの魔力
コードを貼り付けた瞬間、右側のプレビュー画面がどうなったか確認してください。
① 美しいドキュメントの自動生成
わざわざSwagger UIなどの面倒なミドルウェアを立ち上げなくても、右側にプロフェッショナルなAPIドキュメントが爆誕しています。エンドポイント（`/hello`）をクリックすれば、HTTPメソッド、パラメータ、レスポンスの型、サンプルJSONまでが綺麗に整理されて表示されます。これをそのまま非エンジニアのメンバーやクライアントに見せるだけで、「おっ、わかりやすい！」と感動されるはずです。
② モックサーバーを使った動作確認（Debugタブへの連携）
さらにここからがInsomniaの真骨頂です。
「設計図を書いたんだから、実際に動かしてテストしたい」ですよね？
画面上部の 「Debug」 タブに切り替えてみてください。
驚くべきことに、左側のサイドバーに、先ほどYAMLで定義した `/hello` エンドポイントが自動的にリクエストとして生成されています！
Insomniaのデザインモードは、背後で自動的に「モックサーバー」を立ち上げてくれます。
Debugタブで `/hello` リクエストを選択し、「Send」ボタンを押してみてください。
YAMLの `example` に記述した通りのレスポンスが、瞬時に返ってくるのが確認できるはずです。
バックエンドの実装が1行も終わっていなくても、フロントエンド側はこのモックサーバーに向かって画面やクライアント側の実装を進めることができます。これが、開発スピードを数倍に跳ね上げる「API仕様先行開発」の正体です。
—
5. 現場で役立つ！さらに一歩進んだプロの技
この基本形をマスターしたら、少し応用的なテクニックも取り入れていきましょう。
- コンポーネント（Schemas）の再利用:
UserやErrorといった共通のデータ構造は、`components/schemas` 以下に定義し、`$ref` で参照するようにしましょう。仕様書のメンテナンス性が劇的に向上します。
- Git連携によるバージョン管理:
InsomniaのプロジェクトをGitリポジトリとしてエクスポート（またはGit Sync機能を利用）することで、API仕様書の変更履歴をチームでレビューしながら開発できるようになります。「API仕様のプルリクエスト文化」の誕生です。
—
おわりに：明日の開発から、仕様先行を始めよう
今回は、Insomniaの「デザインモード」を使ったOpenAPIの記述から、プレビュー、モックサーバーを駆使した動作確認までの基本を解説しました。
これまでバラバラのツールで行っていた「設計」「ドキュメント化」「モック検証」が、Insomniaという1つの箱の中で完結する心地よさを、ぜひ体感していただけたでしょうか。
「コードを書く前に、まずInsomniaでデザインを書く」
たったこれだけの習慣を取り入れるだけで、チーム内の無駄なすれ違いや手戻りは嘘のように消えていきます。
これをマスターすれば、あなたの毎日の作業が劇的に楽になりますよ。
さあ、次回の開発では、コードを書く前にまずInsomniaを開くことから始めてみませんか？あなたのエンジニアライフが、よりスマートで創造的なものになることを応援しています！