C4 아키텍처 요소에 직접 연결된 API 명세를 문서화하고 관리하세요

API 계약

API 계약을 사용하면 아키텍처 요소에 API 명세를 첨부하여 문서와 설계를 동기화할 수 있습니다. Archyl은 OpenAPI (REST), gRPC, GraphQL, AsyncAPI, MCP 계약을 지원하며 선택적으로 Git 동기화 또는 라이브 검색이 가능합니다.

지원 계약 유형

유형	형식	사용 사례
HTTP (REST)	OpenAPI 3.x (YAML/JSON)	REST API, 웹훅
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이 명세 내용을 가져오고 동기화를 유지합니다

글롭 패턴을 사용하여 여러 파일을 매칭할 수도 있습니다. 예를 들어 api/**/*.yaml은 api/ 디렉토리 아래의 모든 YAML 파일을 매칭합니다.

동기화 동작

계약이 생성될 때 리포지토리에서 명세를 가져옵니다
동기화 버튼을 사용하여 최신 버전을 수동으로 가져올 수 있습니다
마지막 동기화 타임스탬프가 계약 카드에 표시됩니다

MCP 서버

MCP(Model Context Protocol) 서버는 AI 에이전트에게 도구를 노출합니다. 각 도구에는 이름, 설명, 그리고 입력을 위한 JSON Schema가 있습니다. 이 도구 표면도 하나의 계약입니다 ── 에이전트가 무엇을 해도 되는지를 정의합니다. Archyl은 이를 MCP 계약 유형으로 문서화합니다.

다른 유형과 달리 MCP 서버의 도구는 보통 리포지토리의 파일이 아닙니다 ── 권위 있는 목록은 tools/list 호출을 통해 런타임에만 존재합니다. 그래서 MCP 계약은 두 가지 소스를 지원합니다.

도구 목록 붙여넣기

새 계약을 클릭하고 MCP를 선택합니다
소스를 수동으로 유지합니다
서버의 tools/list JSON ── { "tools": [ ... ] } 형태의 객체 ── 를 붙여넣습니다
생성을 클릭합니다

Archyl이 문서를 검증하고 각 도구를 렌더링합니다.

라이브 엔드포인트에서 검색하기

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은 대화형 뷰어로 API 명세를 렌더링합니다:

OpenAPI — 태그별로 그룹화된 엔드포인트, 요청/응답 스키마, 파라미터 및 예시
gRPC — 서비스 정의, RPC 메서드 및 메시지 유형
GraphQL — 타입, 쿼리, 뮤테이션 및 구독
AsyncAPI — 채널, 메시지 및 스키마
MCP — 각 도구와 그 설명, 입력 매개변수(해당 JSON Schema에서)

뷰어는 읽기 전용이며 항상 계약의 현재 내용을 반영합니다.

이벤트 채널

이벤트 채널은 아키텍처의 비동기 메시징 측면을 문서화합니다 — Kafka 토픽, SQS 큐, RabbitMQ 익스체인지 등.

이벤트 채널 생성

프로젝트로 이동합니다
이벤트 채널 탭을 엽니다
새 채널을 클릭합니다
채널을 설정합니다:

필드	설명
이름	채널 이름 (예: "주문 생성 이벤트")
방향	`produce` 또는 `consume`
브로커 유형	Kafka, NATS, SQS, RabbitMQ, Redis, Pulsar 또는 Custom
토픽 이름	실제 토픽 또는 큐 이름
스키마 형식	JSON Schema, Avro, Protobuf 또는 Text
값 스키마	이벤트 페이로드 스키마 정의

아키텍처에 연결

이벤트 채널은 API 계약과 동일한 연결 모델을 따릅니다. 이벤트를 생산하거나 소비하는 시스템, 컨테이너 또는 컴포넌트에 채널을 연결하세요. 이를 통해 아키텍처 다이어그램에서 메시지 흐름을 직접 확인할 수 있습니다.

모범 사례

명세를 최신 상태로 유지

코드베이스에 있는 명세에는 Git 동기화 사용
시맨틱 버저닝에 따라 계약 버전 관리
API가 변경되면 계약 업데이트

모든 것을 연결

API를 제공하는 모든 컨테이너에 최소 하나의 연결된 계약 보유
이벤트 채널을 생산자와 소비자 모두에 연결
링크를 사용하여 다이어그램을 자체 문서화

서비스별로 구성

서비스 또는 바운디드 컨텍스트당 하나의 계약
아키텍처 명명과 일치하는 설명적인 이름 사용
계약 버전 필드에 API 버전 포함

서버 문서화

각 환경에 대한 서버 항목 추가
내부 및 외부 엔드포인트 모두 포함
인프라 변경에 따라 URL 최신화

다음 단계

이벤트 채널 — 비동기 메시징 문서화
아키텍처 변경 요청 — 아키텍처 변경 제안
릴리스 관리 — 시스템 전반의 배포 추적

API 계약 - Archyl Docs