APIコントラクト
APIコントラクトを使用すると、API仕様をアーキテクチャ要素に関連付けて、ドキュメントと設計の同期を保つことができます。ArchylはOpenAPI（REST）、gRPC、GraphQL、AsyncAPIコントラクトをサポートし、オプションでgit同期も可能です。
対応コントラクトタイプ
| タイプ | フォーマット | ユースケース |
|---|---|---|
| HTTP (REST) | OpenAPI 3.x (YAML/JSON) | REST API、Webhook |
| gRPC | Protocol Buffers (.proto) | サービス間RPC |
| GraphQL | GraphQL SDL (.graphql) | クエリAPI |
| Async | AsyncAPI (YAML/JSON) | イベント駆動API、メッセージキュー |
コントラクトの作成
手動入力
- プロジェクトに移動
- APIコントラクトタブを開く
- 新しいコントラクトをクリック
- コントラクトの詳細を入力:
- 名前 — わかりやすい名前（例: 「ユーザーサービスAPI」）
- タイプ — HTTP、gRPC、GraphQL、またはAsync
- バージョン — セマンティックバージョン（例:
1.0.0） - エンドポイント — APIのベースURL
- 説明 — APIの機能
- エディタに仕様の内容を貼り付けまたは記述
- 作成をクリック
Git同期
コントラクトを手動で管理する代わりに、gitリポジトリから同期できます:
- 新しいコントラクトをクリックし、ソースタイプとしてGitを選択
- 接続済みのリポジトリを選択
- 仕様ファイルへのパスを指定（例:
api/openapi.yaml） - 追跡するブランチを設定（デフォルトはリポジトリのデフォルトブランチ）
- Archylが仕様の内容を取得して同期を維持
globパターンを使用して複数のファイルに対応することもできます。例えば、api/**/*.yaml は api/ ディレクトリ下のすべてのYAMLファイルにマッチします。
同期の動作
- コントラクト作成時にリポジトリから仕様が取得される
- 同期ボタンで最新バージョンを手動で取得
- 最終同期のタイムスタンプがコントラクトカードに表示
コントラクトとアーキテクチャのリンク
APIコントラクトはC4要素にリンクすることで真価を発揮します。コントラクトはシステム、コンテナ、コンポーネント、またはコード要素にリンクできます。
リンクの追加
- コントラクトの詳細ページを開く
- 要素にリンクをクリック
- C4レベル（システム、コンテナ、コンポーネント、またはコード）を選択
- 対象要素を選択
- リンクがコントラクトと要素の詳細パネルの両方に表示
リンクされたコントラクトの表示
ダイアグラム上で任意の要素を右クリックすると、詳細パネルが開きます。リンクされたAPIコントラクトはコントラクトセクションに以下とともに表示されます:
- コントラクト名とバージョン
- プロトコルタイプバッジ（HTTP、gRPC、GraphQL、Async）
- 完全な仕様へのリンク
サーバーエントリ
各コントラクトに複数のサーバーエントリを定義できます。異なる環境やリージョンのドキュメント化に便利です。
| フィールド | 説明 |
|---|---|
| URL | サーバーのベースURL（例: https://api.example.com/v1） |
| 説明 | 環境または目的（例: 「本番」、「ステージング」） |
仕様ビューア
Archylはインタラクティブなビューアで仕様をレンダリングします:
- OpenAPI — タグ別にグループ化されたエンドポイント、リクエスト/レスポンススキーマ、パラメータ、例
- gRPC — サービス定義、RPCメソッド、メッセージタイプ
- GraphQL — タイプ、クエリ、ミューテーション、サブスクリプション
- AsyncAPI — チャネル、メッセージ、スキーマ
ビューアは読み取り専用で、常にコントラクトの現在の内容を反映します。
イベントチャネル
イベントチャネルは、アーキテクチャの非同期メッセージング側をドキュメント化します。Kafkaトピック、SQSキュー、RabbitMQエクスチェンジなどが対象です。
イベントチャネルの作成
- プロジェクトに移動
- イベントチャネルタブを開く
- 新しいチャネルをクリック
- チャネルを設定:
| フィールド | 説明 |
|---|---|
| 名前 | チャネル名（例: 「注文作成イベント」） |
| 方向 | produce または consume |
| ブローカータイプ | Kafka、NATS、SQS、RabbitMQ、Redis、Pulsar、またはカスタム |
| トピック名 | 実際のトピックまたはキュー名 |
| スキーマフォーマット | JSON Schema、Avro、Protobuf、またはText |
| 値スキーマ | イベントペイロードのスキーマ定義 |
アーキテクチャへのリンク
イベントチャネルはAPIコントラクトと同じリンクモデルに従います。チャネルを、そのイベントをプロデュースまたはコンシュームするシステム、コンテナ、コンポーネントにリンクします。これにより、メッセージフローがアーキテクチャダイアグラム上で直接確認できます。
ベストプラクティス
仕様を最新に保つ
- コードベースにある仕様にはgit同期を使用
- セマンティックバージョニングに従ってコントラクトをバージョニング
- APIが変更されたらコントラクトを更新
すべてをリンクする
- API提供コンテナには少なくとも1つのリンクされたコントラクト
- イベントチャネルをプロデューサーとコンシューマーの両方にリンク
- リンクを使用してダイアグラムを自己文書化
サービスごとに整理
- サービスまたは境界づけられたコンテキストごとに1つのコントラクト
- アーキテクチャの命名に合致するわかりやすい名前
- コントラクトバージョンフィールドにAPIバージョンを含める
サーバーをドキュメント化
- 各環境のサーバーエントリを追加
- 内部と外部の両方のエンドポイントを含める
- インフラストラクチャの変更に応じてURLを最新に保つ
次のステップ
- イベントチャネル — 非同期メッセージングのドキュメント化
- アーキテクチャ変更リクエスト — アーキテクチャへの変更を提案
- リリース管理 — システム全体のデプロイメントを追跡