C4アーキテクチャ要素に直接リンクされたAPI仕様のドキュメント化と管理

APIコントラクト

APIコントラクトを使用すると、API仕様をアーキテクチャ要素に関連付けて、ドキュメントと設計の同期を保つことができます。ArchylはOpenAPI（REST）、gRPC、GraphQL、AsyncAPI、MCPコントラクトをサポートし、オプションで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、メッセージキュー
MCP	MCP `tools/list` (JSON)	AIエージェントに公開されるツール

コントラクトの作成

手動入力

プロジェクトに移動
APIコントラクトタブを開く
新しいコントラクトをクリック
コントラクトの詳細を入力:
- 名前 — わかりやすい名前（例: 「ユーザーサービスAPI」）
- タイプ — HTTP、gRPC、GraphQL、Async、またはMCP
- バージョン — セマンティックバージョン（例: 1.0.0）
- エンドポイント — APIのベースURL
- 説明 — APIの機能
エディタに仕様の内容を貼り付けまたは記述
作成をクリック

Git同期

コントラクトを手動で管理する代わりに、gitリポジトリから同期できます:

新しいコントラクトをクリックし、ソースタイプとしてGitを選択
接続済みのリポジトリを選択
仕様ファイルへのパスを指定（例: api/openapi.yaml）
追跡するブランチを設定（デフォルトはリポジトリのデフォルトブランチ）
Archylが仕様の内容を取得して同期を維持

globパターンを使用して複数のファイルに対応することもできます。例えば、api/**/*.yaml は api/ ディレクトリ下のすべてのYAMLファイルにマッチします。

同期の動作

コントラクト作成時にリポジトリから仕様が取得される
同期ボタンで最新バージョンを手動で取得
最終同期のタイムスタンプがコントラクトカードに表示

MCPサーバー

MCP（Model Context Protocol）サーバーは AI エージェントにツールを公開します。各ツールには名前、説明、入力用の JSON Schema があります。このツール面もまた契約です ── エージェントが何をしてよいかを定義します。Archyl はこれを MCP コントラクトタイプとしてドキュメント化します。

他のタイプと異なり、MCP サーバーのツールは通常リポジトリ内のファイルではありません ── 正式な一覧は tools/list 呼び出しによって実行時にのみ存在します。そのため MCP コントラクトは 2 つのソースに対応します。

ツール一覧を貼り付ける

新しいコントラクトをクリックし、MCP を選択
ソースは手動のままにする
サーバーの tools/list JSON ──{ "tools": [ ... ] } の形式のオブジェクト── を貼り付ける
作成をクリック

Archyl が文書を検証し、各ツールを表示します。

ライブエンドポイントから検出する

実行中のサーバーから直接ツールを取得させます:

新しいコントラクトをクリックし、MCP を選び、ソースとして Live endpoint を選択
サーバーの URL を入力し、トランスポート（HTTP または SSE）を選ぶ
サーバーが認証を必要とする場合、トークンの送り先 ──ヘッダー（例: X-API-Key）またはクエリパラメータ── を選び、トークンを入力
ツールを検出をクリック ── Archyl が接続し、ハンドシェイクを実行し、各ツールとそのパラメータを一覧表示
検出されたツールを確認し、作成をクリック

後でツールを更新するには、コントラクトを編集して再度ツールを検出を実行します。

検出は Archyl のサーバーではなく、あなたのブラウザで実行されます。 トークンがブラウザから出ることは決してありません ── Archyl は検出されたツールと接続情報（URL、トランスポート、ヘッダー/パラメータ名）を保存しますが、トークン自体は決して保存しません。呼び出しはあなたのマシンから始まるため、localhost やプライベートネットワーク上のサーバーにも到達できます。

唯一の要件: あなたのブラウザが応答を読めるように、MCP サーバーがこのサイトのオリジンを許可している必要があります（CORS）。あなたが管理するサーバーなら設定の小さな変更で済みます。そうでなければ、上記の貼り付けオプションを使ってください。

MCP ツールビューア

各ツールは、名前、説明、入力パラメータ（その JSON Schema から導出）とともに表示され、ツールごとに生のスキーマも参照できます。他のコントラクトタイプと同様、ビューアは読み取り専用で、保存されたツール一覧を反映します。

コントラクトとアーキテクチャのリンク

APIコントラクトはC4要素にリンクすることで真価を発揮します。コントラクトはシステム、コンテナ、コンポーネント、またはコード要素にリンクできます。

リンクの追加

コントラクトの詳細ページを開く
要素にリンクをクリック
C4レベル（システム、コンテナ、コンポーネント、またはコード）を選択
対象要素を選択
リンクがコントラクトと要素の詳細パネルの両方に表示

リンクされたコントラクトの表示

ダイアグラム上で任意の要素を右クリックすると、詳細パネルが開きます。リンクされたAPIコントラクトはコントラクトセクションに以下とともに表示されます:

コントラクト名とバージョン
プロトコルタイプバッジ（HTTP、gRPC、GraphQL、Async、MCP）
完全な仕様へのリンク

サーバーエントリ

各コントラクトに複数のサーバーエントリを定義できます。異なる環境やリージョンのドキュメント化に便利です。

フィールド	説明
URL	サーバーのベースURL（例: `https://api.example.com/v1`）
説明	環境または目的（例: 「本番」、「ステージング」）

仕様ビューア

Archylはインタラクティブなビューアで仕様をレンダリングします:

OpenAPI — タグ別にグループ化されたエンドポイント、リクエスト/レスポンススキーマ、パラメータ、例
gRPC — サービス定義、RPCメソッド、メッセージタイプ
GraphQL — タイプ、クエリ、ミューテーション、サブスクリプション
AsyncAPI — チャネル、メッセージ、スキーマ
MCP — 各ツールとその説明、入力パラメータ（JSON Schema から）

ビューアは読み取り専用で、常にコントラクトの現在の内容を反映します。

イベントチャネル

イベントチャネルは、アーキテクチャの非同期メッセージング側をドキュメント化します。Kafkaトピック、SQSキュー、RabbitMQエクスチェンジなどが対象です。

イベントチャネルの作成

プロジェクトに移動
イベントチャネルタブを開く
新しいチャネルをクリック
チャネルを設定:

フィールド	説明
名前	チャネル名（例: 「注文作成イベント」）
方向	`produce` または `consume`
ブローカータイプ	Kafka、NATS、SQS、RabbitMQ、Redis、Pulsar、またはカスタム
トピック名	実際のトピックまたはキュー名
スキーマフォーマット	JSON Schema、Avro、Protobuf、またはText
値スキーマ	イベントペイロードのスキーマ定義

アーキテクチャへのリンク

イベントチャネルはAPIコントラクトと同じリンクモデルに従います。チャネルを、そのイベントをプロデュースまたはコンシュームするシステム、コンテナ、コンポーネントにリンクします。これにより、メッセージフローがアーキテクチャダイアグラム上で直接確認できます。

ベストプラクティス

仕様を最新に保つ

コードベースにある仕様にはgit同期を使用
セマンティックバージョニングに従ってコントラクトをバージョニング
APIが変更されたらコントラクトを更新

すべてをリンクする

API提供コンテナには少なくとも1つのリンクされたコントラクト
イベントチャネルをプロデューサーとコンシューマーの両方にリンク
リンクを使用してダイアグラムを自己文書化

サービスごとに整理

サービスまたは境界づけられたコンテキストごとに1つのコントラクト
アーキテクチャの命名に合致するわかりやすい名前
コントラクトバージョンフィールドにAPIバージョンを含める

サーバーをドキュメント化

各環境のサーバーエントリを追加
内部と外部の両方のエンドポイントを含める
インフラストラクチャの変更に応じてURLを最新に保つ

次のステップ

イベントチャネル — 非同期メッセージングのドキュメント化
アーキテクチャ変更リクエスト — アーキテクチャへの変更を提案
リリース管理 — システム全体のデプロイメントを追跡

APIコントラクト - Archyl Docs