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

API 계약

API 계약을 사용하면 아키텍처 요소에 API 명세를 첨부하여 문서와 설계를 동기화할 수 있습니다. Archyl은 OpenAPI (REST), gRPC, GraphQL, AsyncAPI 계약을 지원하며 선택적으로 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, 메시지 큐

계약 생성

수동 입력

프로젝트로 이동합니다
API 계약 탭을 엽니다
새 계약을 클릭합니다
계약 세부사항을 입력합니다:
- 이름 — 설명적인 이름 (예: "사용자 서비스 API")
- 유형 — HTTP, gRPC, GraphQL 또는 Async
- 버전 — 시맨틱 버전 (예: 1.0.0)
- 엔드포인트 — API의 기본 URL
- 설명 — API의 기능
에디터에서 명세 내용을 붙여넣거나 작성합니다
생성을 클릭합니다

Git 동기화

계약을 수동으로 관리하는 대신 Git 리포지토리에서 동기화할 수 있습니다:

새 계약을 클릭하고 소스 유형으로 Git을 선택합니다
연결된 리포지토리를 선택합니다
명세 파일 경로를 지정합니다 (예: api/openapi.yaml)
추적할 브랜치를 설정합니다 (기본값은 리포지토리의 기본 브랜치)
Archyl이 명세 내용을 가져오고 동기화를 유지합니다

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

동기화 동작

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

계약을 아키텍처에 연결

API 계약은 설명하는 C4 요소에 연결될 때 의미가 있습니다. 계약은 시스템, 컨테이너, 컴포넌트 또는 코드 요소에 연결할 수 있습니다.

링크 추가

계약의 상세 페이지를 엽니다
요소에 연결을 클릭합니다
C4 레벨을 선택합니다 (시스템, 컨테이너, 컴포넌트 또는 코드)
대상 요소를 선택합니다
링크가 계약과 요소의 세부 패널 모두에 나타납니다

연결된 계약 보기

다이어그램에서 요소를 우클릭하여 세부 패널을 엽니다. 연결된 API 계약이 계약 섹션에 다음과 함께 표시됩니다:

계약 이름 및 버전
프로토콜 유형 배지 (HTTP, gRPC, GraphQL, Async)
전체 명세 링크

서버 항목

각 계약은 여러 서버 항목을 정의할 수 있습니다. 다양한 환경이나 리전을 문서화하는 데 유용합니다.

필드	설명
URL	서버 기본 URL (예: `https://api.example.com/v1`)
설명	환경 또는 목적 (예: "운영", "스테이징")

명세 뷰어

Archyl은 대화형 뷰어로 API 명세를 렌더링합니다:

OpenAPI — 태그별로 그룹화된 엔드포인트, 요청/응답 스키마, 파라미터 및 예시
gRPC — 서비스 정의, RPC 메서드 및 메시지 유형
GraphQL — 타입, 쿼리, 뮤테이션 및 구독
AsyncAPI — 채널, 메시지 및 스키마

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

이벤트 채널

이벤트 채널은 아키텍처의 비동기 메시징 측면을 문서화합니다 — 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