Vendure API ドキュメント・可視化ガイド¶

概要¶

本プロジェクトの API 面は GraphQL と REST の併用です。

GraphQL: Vendure 標準の Shop API / Admin API と、その schema extension
REST: Webhook / callback / download / 監視 / 外部 CMS 検索の一部

どちらを選ぶべきかの判断基準は、REST / GraphQL 境界方針を正本にしてください。

API可視化ツール¶

GraphiQL（標準搭載）¶

Vendure には GraphiQL が組み込まれており、GraphQL 面を探索・テストできます。

アクセスURL¶

Shop API:
Portless: http://vendure.localhost:<worktree-proxy-port>/graphiql/shop
localhost: http://localhost:${VENDURE_PORT:-3021}/graphiql/shop
Admin API:
Portless: http://vendure.localhost:<worktree-proxy-port>/graphiql/admin
localhost: http://localhost:${VENDURE_PORT:-3021}/graphiql/admin
デモ環境: https://demo.vendure.io/graphiql/shop

主要機能¶

1. インタラクティブな探索¶

スキーマを視覚的にナビゲート
ドリルダウンによるデータ構造の探索
必要なフィールドのみを選択して取得

2. 自動補完機能¶

Ctrl/⌘ + Spaceで利用可能なフィールドを表示
型情報の即座の確認
クエリ作成の効率化

3. ドキュメント自動生成¶

スキーマ定義から自動的にドキュメントを生成
各フィールドの説明と型情報を表示
"Docs"アイコンからドキュメントエクスプローラーにアクセス

4. リアルタイムテスト¶

クエリやミューテーションを即座に実行
レスポンスをリアルタイムで確認
エラーメッセージの詳細表示

使用例¶

商品一覧を取得するクエリ¶

query GetProducts {
  products {
    items {
      id
      name
      slug
      description
      variants {
        id
        sku
        price
      }
    }
    totalItems
  }
}

管理者APIでの商品作成¶

mutation CreateProduct {
  createProduct(
    input: {
      translations: [
        { languageCode: ja, name: "新商品", slug: "new-product", description: "商品説明" }
      ]
    }
  ) {
    id
    name
  }
}

Swagger / OpenAPI（REST 面）¶

この repo では Nest controller ベースの REST endpoint 向けに /api-docs を有効化できます。

実装箇所: apps/vendure-server/src/index.ts
公開条件: NODE_ENV !== "production"、または VENDURE_API_DOCS_ENABLED=true を明示的に設定。
production では既定で無効 (Swagger UI / OpenAPI JSON は serve されない)。
System Integration の webhook spec を外部に露出させないための hardening。
production で一時的に有効化したい場合は VENDURE_API_DOCS_ENABLED=true を Fly secret に設定する。
主対象: system-integration/shipment などの REST controller

ただし、Vendure 全体の API を OpenAPI 化しているわけではありません。Shop API / Admin API は GraphQL なので、Swagger / Redoc / Scalar の主対象ではありません。

SwaggerやRedocとの違い¶

なぜSwagger/Redocが使えないのか¶

Swagger/Redoc: REST API（OpenAPI仕様）専用のドキュメントツール
GraphQL: 独自のイントロスペクションを持ち、GraphiQL / schema explorer で探索する
本プロジェクトの整理: first-party UI 向けは GraphQL、外部連携や HTTP semantics が主役の面は REST

GraphQLの利点¶

セルフドキュメンティング: スキーマ自体がドキュメントとして機能
型安全性: 強力な型システムによる開発時のエラー防止
単一エンドポイント: shop-api / admin-api で機能群にアクセス
フィールド選択: 必要なデータのみを取得（オーバーフェッチの防止）

開発ワークフロー¶

1. API探索フロー¶

GraphiQLを開く
Docsパネルでスキーマを確認
クエリを作成（自動補完を活用）
実行してレスポンスを確認

2. プラグイン開発時の確認¶

カスタムプラグインを追加した場合：

サーバーを再起動
GraphiQLでスキーマの更新を確認
新しいフィールドやミューテーションをテスト

3. フロントエンド開発との連携¶

// Storefront での使用例
import { graphql } from "@/__generated__/gql";

const GET_PRODUCTS = graphql(`
  query GetProducts {
    products {
      items {
        id
        name
        slug
      }
    }
  }
`);

ベストプラクティス¶

1. 開発環境での活用¶

GraphiQLを常に開いておき、APIの変更を即座に確認
クエリの保存機能を活用して、頻繁に使用するクエリを管理

2. ドキュメント化¶

カスタムプラグインには必ず@Descriptionデコレータでドキュメントを追加
GraphiQLで表示される説明文を充実させる

@Resolver()
export class CustomResolver {
  @Query()
  @Description("カスタム価格計算を実行します")
  calculateCustomPrice(@Args() args: CustomPriceArgs): number {
    // 実装
  }
}

3. チーム共有¶

よく使うクエリをMarkdownファイルとして保存
GraphiQLのURLを共有してチーム内でAPIを確認

トラブルシューティング¶

GraphiQLが表示されない場合¶

Vendureサーバーが起動しているか確認
ポート3021が使用可能か確認
vendure-config.tsでGraphiQLが有効になっているか確認

export const config: VendureConfig = {
  apiOptions: {
    playground: true, // 本番環境ではfalseに設定
    introspection: true, // 本番環境では検討が必要
  },
};

クエリエラーの対処¶

エラーメッセージを確認（GraphiQLの右パネル）
必須フィールドの不足をチェック
権限エラーの場合は認証トークンを確認

`/api-docs` が表示されない場合¶

apps/vendure-server/src/index.ts の Swagger 初期化が失敗していないかログを確認する
production 環境なら ENABLE_API_DOCS=true になっているか確認する
対象 controller に Swagger annotation が付いているか確認する
GraphQL 面を見たい場合は /api-docs ではなく GraphiQL を使う