mcpField
I
insomnia-collection-generator

insomnia-collection-generator

github.com/patricio0312rev開発63265 回インストール41 週間前に更新
リポジトリ

insomnia-collection-generator について

API 開発者向けの Insomnia コレクション生成スキルです。コード内のルートからリクエスト情報を抽出し、環境設定や認証を含むインポート可能な Insomnia v4 ワークスペース JSON を作成します。

主な機能

  1. 01API ルートを走査してリクエスト情報を抽出
  2. 02リソース別にワークスペースのリクエストを整理
  3. 03ベース URL と環境変数を設定
  4. 04Bearer、Basic、API Key 認証を設定
  5. 05Insomnia v4 JSON をエクスポート

活用シーン

  1. 01既存の API コードから Insomnia ワークスペースを生成
  2. 02開発、ステージング、本番環境向けの設定を準備
  3. 03リクエストメソッド、パスパラメーター、ボディを整理
  4. 04API リクエストコレクションをバージョン管理

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/patricio0312rev/skills --skill insomnia-collection-generator

インストール後、Claude Code で/insomnia-collection-generatorを入力して読み込まれたか確認します。

詳細

Insomnia コレクションジェネレーター

API コードベースから、インポート可能な Insomnia ワークスペースを自動生成します。

基本的なワークフロー

  1. ルートをスキャン：すべての API ルート定義を検索します
  2. メタデータを抽出：メソッド、パス、パラメーター、ボディを抽出します
  3. ワークスペースを作成：リクエストをグループに整理します
  4. 環境を設定：ベース URL、認証トークンを設定します
  5. 認証を追加：Bearer、Basic、API キーを設定します
  6. コレクションをエクスポート：Insomnia v4 JSON 形式でエクスポートします

Insomnia エクスポート v4 スキーマ

{
  "_type": "export",
  "__export_format": 4,
  "__export_date": "2024-01-15T10:30:00.000Z",
  "__export_source": "insomnia.desktop.app:v2023.5.8",
  "resources": []
}

リソースの種類

interface InsomniaWorkspace {
  _id: string;
  _type: "workspace";
  name: string;
  description: string;
  scope: "collection" | "design";
}

interface InsomniaRequestGroup {
  _id: string;
  _type: "request_group";
  name: string;
  parentId: string;
  description?: string;
}

interface InsomniaRequest {
  _id: string;
  _type: "request";
  name: string;
  parentId: string;
  method: string;
  url: string;
  body: InsomniaBody;
  headers: InsomniaHeader[];
  parameters: InsomniaParameter[];
  authentication: InsomniaAuth;
}

interface InsomniaEnvironment {
  _id: string;
  _type: "environment";
  name: string;
  parentId: string;
  data: Record<string, string>;
}

コレクションジェネレーター

// scripts/generate-insomnia.ts
import { v4 as uuidv4 } from "uuid";

interface RouteInfo {
  method: string;
  path: string;
  name: string;
  body?: object;
  params?: { name: string; type: "path" | "query" }[];
}

interface InsomniaExport {
  _type: "export";
  __export_format: 4;
  __export_date: string;
  __export_source: string;
  resources: InsomniaResource[];
}

type InsomniaResource =
  | InsomniaWorkspace
  | InsomniaRequestGroup
  | InsomniaRequest
  | InsomniaEnvironment;

function generateInsomniaCollection(
  routes: RouteInfo[],
  options: {
    name: string;
    baseUrl: string;
    description?: string;
  }
): InsomniaExport {
  const workspaceId = `wrk_${uuidv4().replace(/-/g, "")}`;
  const baseEnvId = `env_${uuidv4().replace(/-/g, "")}`;
  const devEnvId = `env_${uuidv4().replace(/-/g, "")}`;

  const resources: InsomniaResource[] = [];

  // Create workspace
  resources.push({
    _id: workspaceId,
    _type: "workspace",
    name: options.name,
    description: options.description || "Auto-generated API collection",
    scope: "collection",
  });

  // Create base environment
  resources.push({
    _id: baseEnvId,
    _type: "environment",
    name: "Base Environment",
    parentId: workspaceId,
    data: {},
  });

  // Create development environment
  resources.push({
    _id: devEnvId,
    _type: "environment",
    name: "Development",
    parentId: baseEnvId,
    data: {
      base_url: options.baseUrl,
      auth_token: "",
    },
  });

  // Group routes by resource
  const groupedRoutes = groupRoutesByResource(routes);

  for (const [resource, resourceRoutes] of Object.entries(groupedRoutes)) {
    // Create request group (folder)
    const groupId = `fld_${uuidv4().replace(/-/g, "")}`;

    resources.push({
      _id: groupId,
      _type: "request_group",
      name: capitalize(resource),
      parentId: workspaceId,
      description: `${resource} endpoints`,
    });

    // Create requests in group
    for (const route of resourceRoutes) {
      resources.push(createInsomniaRequest(route, groupId));
    }
  }

  return {
    _type: "export",
    __export_format: 4,
    __export_date: new Date().toISOString(),
    __export_source: "api-generator:v1.0.0",
    resources,
  };
}

function createInsomniaRequest(
  route: RouteInfo,
  parentId: string
): InsomniaRequest {
  const requestId = `req_${uuidv4().replace(/-/g, "")}`;

  // Convert :param to {{ _.param }} for Insomnia
  const url = route.path.replace(/:(\w+)/g, "{{ _.$1 }}");

  const request: InsomniaRequest = {
    _id: requestId,
    _type: "request",
    name: route.name,
    parentId,
    method: route.method,
    url: `{{ _.base_url }}${url}`,
    body: {
      mimeType: "application/json",
      text: route.body ? JSON.stringify(route.body, null, 2) : "",
    },
    headers: [
      {
        name: "Content-Type",
        value: "application/json",
      },
    ],
    parameters: route.params
      ?.filter((p) => p.type === "query")
      .map((p) => ({
        name: p.name,
        value: "",
        disabled: false,
      })) || [],
    authentication: {
      type: "bearer",
      token: "{{ _.auth_token }}",
      disabled: true,
    },
  };

  return request;
}

function groupRoutesByResource(
  routes: RouteInfo[]
): Record<string, RouteInfo[]> {
  const groups: Record<string, RouteInfo[]> = {};

  for (const route of routes) {
    const parts = route.path.split("/").filter(Boolean);
    const resource = parts[0] || "root";

    if (!groups[resource]) {
      groups[resource] = [];
    }
    groups[resource].push(route);
  }

  return groups;
}

function capitalize(str: string): string {
  return str.charAt(0).toUpperCase() + str.slice(1);
}

エクスポートの完全な例

{
  "_type": "export",
  "__export_format": 4,
  "__export_date": "2024-01-15T10:30:00.000Z",
  "__export_source": "api-generator:v1.0.0",
  "resources": [
    {
      "_id": "wrk_abc123",
      "_type": "workspace",
      "name": "My API",
      "description": "Auto-generated API collection",
      "scope": "collection"
    },
    {
      "_id": "env_base123",
      "_type": "environment",
      "name": "Base Environment",
      "parentId": "wrk_abc123",
      "data": {}
    },
    {
      "_id": "env_dev123",
      "_type": "environment",
      "name": "Development",
      "parentId": "env_base123",
      "data": {
        "base_url": "http://localhost:3000/api",
        "auth_token": ""
      }
    },
    {
      "_id": "env_prod123",
      "_type": "environment",
      "name": "Production",
      "parentId": "env_base123",
      "data": {
        "base_url": "https://api.example.com",
        "auth_token": ""
      }
    },
    {
      "_id": "fld_users123",
      "_type": "request_group",
      "name": "Users",
      "parentId": "wrk_abc123"
    },
    {
      "_id": "req_getusers",
      "_type": "request",
      "name": "Get All Users",
      "parentId": "fld_users123",
      "method": "GET",
      "url": "{{ _.base_url }}/users",
      "body": {},
      "headers": [
        { "name": "Content-Type", "value": "application/json" }
      ],
      "parameters": [
        { "name": "page", "value": "1", "disabled": false },
        { "name": "limit", "value": "10", "disabled": false }
      ],
      "authentication": {
        "type": "bearer",
        "token": "{{ _.auth_token }}"
      }
    },
    {
      "_id": "req_getuser",
      "_type": "request",
      "name": "Get User by ID",
      "parentId": "fld_users123",
      "method": "GET",
      "url": "{{ _.base_url }}/users/{{ _.user_id }}",
      "body": {},
      "headers": [],
      "authentication": {}
    },
    {
      "_id": "req_createuser",
      "_type": "request",
      "name": "Create User",
      "parentId": "fld_users123",
      "method": "POST",
      "url": "{{ _.base_url }}/users",
      "body": {
        "mimeType": "application/json",
        "text": "{\n  \"name\": \"John Doe\",\n  \"email\": \"[email protected]\"\n}"
      },
      "headers": [
        { "name": "Content-Type", "value": "application/json" }
      ],
      "authentication": {
        "type": "bearer",
        "token": "{{ _.auth_token }}"
      }
    }
  ]
}

認証の種類

// Bearer Token
{
  "type": "bearer",
  "token": "{{ _.auth_token }}",
  "prefix": "Bearer"
}

// Basic Auth
{
  "type": "basic",
  "username": "{{ _.username }}",
  "password": "{{ _.password }}"
}

// API Key
{
  "type": "apikey",
  "key": "X-API-Key",
  "value": "{{ _.api_key }}",
  "addTo": "header"
}

// OAuth 2.0
{
  "type": "oauth2",
  "grantType": "authorization_code",
  "authorizationUrl": "https://auth.example.com/authorize",
  "accessTokenUrl": "https://auth.example.com/token",
  "clientId": "{{ _.client_id }}",
  "clientSecret": "{{ _.client_secret }}",
  "scope": "read write"
}

リクエストボディの種類

// JSON Body
{
  "mimeType": "application/json",
  "text": "{\"name\": \"value\"}"
}

// Form URL Encoded
{
  "mimeType": "application/x-www-form-urlencoded",
  "params": [
    { "name": "field1", "value": "value1" },
    { "name": "field2", "value": "value2" }
  ]
}

// Multipart Form (file upload)
{
  "mimeType": "multipart/form-data",
  "params": [
    { "name": "file", "type": "file", "fileName": "" },
    { "name": "description", "value": "File description" }
  ]
}

// GraphQL
{
  "mimeType": "application/graphql",
  "text": "query { users { id name } }"
}

CLI スクリプト

#!/usr/bin/env node
// scripts/insomnia-gen.ts
import * as fs from "fs";
import { program } from "commander";

program
  .name("insomnia-gen")
  .description("Generate Insomnia collection from API routes")
  .option("-f, --framework <type>", "Framework type", "express")
  .option("-s, --source <path>", "Source directory", "./src")
  .option("-o, --output <path>", "Output file", "./insomnia-collection.json")
  .option("-n, --name <name>", "Workspace name", "API Collection")
  .option("-b, --base-url <url>", "Base URL", "http://localhost:3000/api")
  .parse();

const options = program.opts();

async function main() {
  const routes = await scanRoutes(options.framework, options.source);

  const collection = generateInsomniaCollection(routes, {
    name: options.name,
    baseUrl: options.baseUrl,
  });

  fs.writeFileSync(options.output, JSON.stringify(collection, null, 2));
  console.log(`Generated ${options.output} with ${routes.length} requests`);
}

main();

環境テンプレート

{
  "_id": "env_development",
  "_type": "environment",
  "name": "Development",
  "data": {
    "base_url": "http://localhost:3000/api",
    "auth_token": "",
    "user_id": "1"
  }
}

{
  "_id": "env_staging",
  "_type": "environment",
  "name": "Staging",
  "data": {
    "base_url": "https://staging-api.example.com",
    "auth_token": "",
    "user_id": "test-user-123"
  }
}

{
  "_id": "env_production",
  "_type": "environment",
  "name": "Production",
  "data": {
    "base_url": "https://api.example.com",
    "auth_token": "",
    "user_id": ""
  }
}

ベストプラクティス

  1. 環境を使用：ベース URL とトークンを変数として保存します
  2. フォルダーを整理：リクエストをリソースや機能ごとにグループ化します
  3. テンプレート構文：動的な値には {{ _.variable }} を使用します
  4. 認証：可能であればワークスペースレベルで設定します
  5. 説明を追加：各リクエストの目的を記述します
  6. 例を含める：リクエストボディに現実的なデータを事前入力します
  7. バージョン管理：エクスポートした JSON をリポジトリにコミットします
  8. 複数の環境：開発、ステージング、本番環境を作成します

出力チェックリスト

  • コードベース内のすべてのルートをスキャン済み
  • 適切なスコープでワークスペースを作成済み
  • リクエストグループをリソースごとに整理済み
  • リクエストに適切なメソッドと URL を設定済み
  • パスパラメーターを {{ _.param }} 構文に変換済み
  • POST／PUT／PATCH 用のリクエストボディを追加済み
  • ヘッダーを設定済み（Content-Type など）
  • 環境を作成済み（dev、staging、prod）
  • 認証を設定済み
  • Insomnia でエクスポートを検証済み

コメント

Markdown 対応