Vendure API ドキュメント・可視化ガイド¶
概要¶
VendureはGraphQL APIを採用しており、RESTベースのSwaggerやRedocではなく、GraphQL専用のドキュメントツールを提供しています。
API可視化ツール¶
GraphiQL（標準搭載）¶
VendureにはGraphiQLが組み込まれており、開発時にAPIを探索・テストできます。
アクセスURL¶
- Shop API:
http://localhost:3000/graphiql/shop - Admin API:
http://localhost:3000/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やRedocとの違い¶
なぜSwagger/Redocが使えないのか¶
- Swagger/Redoc: REST API（OpenAPI仕様）専用のドキュメントツール
- GraphQL: 異なるエコシステムで動作し、独自のイントロスペクション機能を持つ
- 互換性: 2021年時点で、GraphQLとOpenAPIの相互運用標準は存在しない
GraphQLの利点¶
- セルフドキュメンティング: スキーマ自体がドキュメントとして機能
- 型安全性: 強力な型システムによる開発時のエラー防止
- 単一エンドポイント:
/graphqlのみで全機能にアクセス - フィールド選択: 必要なデータのみを取得（オーバーフェッチの防止）
開発ワークフロー¶
1. API探索フロー¶
- GraphiQLを開く
- Docsパネルでスキーマを確認
- クエリを作成（自動補完を活用）
- 実行してレスポンスを確認
2. プラグイン開発時の確認¶
カスタムプラグインを追加した場合：
- サーバーを再起動
- GraphiQLでスキーマの更新を確認
- 新しいフィールドやミューテーションをテスト
3. フロントエンド開発との連携¶
// Next.jsでの使用例
import { gql } from '@apollo/client';
const GET_PRODUCTS = gql`
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サーバーが起動しているか確認
- ポート3000が使用可能か確認
vendure-config.tsでGraphiQLが有効になっているか確認
export const config: VendureConfig = {
apiOptions: {
playground: true, // 本番環境ではfalseに設定
introspection: true, // 本番環境では検討が必要
},
};
クエリエラーの対処¶
- エラーメッセージを確認（GraphiQLの右パネル）
- 必須フィールドの不足をチェック
- 権限エラーの場合は認証トークンを確認