AsyncAPI Reference

AsyncAPI 비동기 API 레퍼런스

25개 결과

AsyncAPI Reference 소개

AsyncAPI 레퍼런스는 이벤트 기반 API와 메시지 기반 아키텍처를 위한 오픈소스 명세인 AsyncAPI 3.0의 핵심 문법을 검색 가능하게 정리한 치트 시트입니다. 채널(asyncapi 버전 선언, 주소가 있는 채널 정의, send/receive 액션 오퍼레이션, 동적 주소 파라미터), 메시지(contentType이 있는 구조, headers/correlationId/timestamp, messageTraits 재사용), 서버(호스트와 프로토콜 브로커 정의, Kafka/AMQP/MQTT/WebSocket/NATS 지원 프로토콜), 바인딩(Kafka 토픽/파티션/레플리카, AMQP 큐 durable/exclusive, MQTT QoS/retain/clientId, WebSocket 메서드/쿼리), 스키마(JSON Schema 페이로드, $ref 컴포넌트 재사용, oneOf/anyOf 다형성 메시지, enum 제약), 보안(apiKey, OAuth2 clientCredentials, userPassword, X509, Kafka용 SASL, 채널 수준 보안) 6개 섹션을 다룹니다.

AsyncAPI는 이벤트 기반 시스템을 설계하고 문서화하는 플랫폼 엔지니어, 백엔드 개발자, API 아키텍트가 사용합니다. OpenAPI가 REST API의 요청/응답 패턴을 문서화하듯, AsyncAPI는 Kafka, RabbitMQ, MQTT, WebSocket 등의 프로토콜에서 발행/구독 및 요청/응답 패턴을 사용하는 메시지 브로커 API를 문서화합니다. 하나의 스펙 파일에서 문서, 클라이언트 SDK, 서버 스텁, 유효성 검사 스키마를 생성하는 데 활용됩니다.

AsyncAPI 3.0 명세는 채널(메시지가 흐르는 곳)과 오퍼레이션(발생하는 액션)을 더 명확하게 분리하여 프로토콜에 더 독립적인 명세를 만들었습니다. 바인딩 시스템은 핵심 채널/메시지 정의를 오염시키지 않고 프로토콜별 구성을 가능하게 합니다. 이 레퍼런스는 이 모든 개념을 6개의 직관적인 카테고리로 정리하여 YAML 예제와 함께 제공합니다. 브라우저에서 실행되며 회원가입 없이 무료로 사용할 수 있고 다크 모드를 지원합니다.

주요 기능

채널 정의: 주소, 동적 {userId} 경로 세그먼트가 있는 채널 수준 파라미터, 메시지 참조
오퍼레이션: AsyncAPI 3.0 오퍼레이션 모델을 위한 채널 및 메시지 $ref를 이용한 send/receive 액션 유형
메시지 구조: contentType, 이름/제목 메타데이터, 페이로드 $ref, correlationId와 timestamp가 있는 헤더
메시지 traits: 여러 채널에 걸쳐 DRY 메시지 정의를 위한 traceId가 있는 재사용 가능한 commonHeaders
서버 바인딩: Kafka(토픽, 파티션, 레플리카, 키 스키마), AMQP(큐 이름, durable, exclusive), MQTT(QoS, retain, clientId), WebSocket(메서드, 쿼리 파라미터)
JSON Schema 페이로드: required 배열, 속성 유형, 형식 제약(email, date-time), $ref 재사용, 다형성 이벤트 유형을 위한 oneOf/anyOf, enum 값
보안 체계: apiKey(user/password/cookie), 스코프가 있는 OAuth2 clientCredentials, userPassword, X509 클라이언트 인증서, Kafka용 SASL scramSha256
명명된 securitySchemes 컴포넌트의 $ref를 통한 채널 수준 및 서버 수준 보안 적용

자주 묻는 질문

AsyncAPI란 무엇이며 OpenAPI와 어떻게 다른가요?

AsyncAPI는 메시지 브로커와 발행/구독 패턴을 사용하는 이벤트 기반 API를 문서화하는 명세입니다. OpenAPI가 HTTP 요청/응답 사이클의 동기 REST API를 문서화하는 반면, AsyncAPI는 프로듀서가 메시지를 채널(Kafka 토픽, AMQP 큐, MQTT 토픽)에 발행하고 컨슈머가 구독하는 비동기 API를 문서화합니다. 바인딩 시스템을 통해 Kafka, RabbitMQ/AMQP, MQTT, WebSocket, NATS 등을 지원합니다.

AsyncAPI 3.0에서 채널과 오퍼레이션의 변경 사항은?

AsyncAPI 3.0에서 채널과 오퍼레이션이 별도의 최상위 객체로 분리되었습니다. 채널은 메시지가 흐르는 위치(주소와 메시지 스키마)를 정의하고, 오퍼레이션은 해당 채널에서 발생하는 액션(send 또는 receive)을 정의합니다. 이 분리로 명세가 더 프로토콜 독립적이 되었고, 오퍼레이션이 명시적 메시지 $ref 배열을 통해 처리하는 메시지 유형을 정확히 지정할 수 있습니다.

AsyncAPI에서 Kafka 토픽을 파티션 및 복제 설정과 함께 정의하는 방법은?

채널 정의에 "bindings.kafka" 블록을 추가합니다. "topic"으로 Kafka 토픽 이름, "partitions"로 파티션 수, "replicas"로 복제 팩터, 선택적으로 메시지 키 유형을 정의하는 "key" 스키마를 지정합니다. 이 Kafka 전용 설정은 바인딩에 포함되어 일반 채널/메시지 구조에 영향을 주지 않습니다.

correlationId란 무엇이며 AsyncAPI에서 왜 중요한가요?

correlationId는 요청/응답 패턴에서 요청 메시지와 해당 응답 메시지를 연결합니다. AsyncAPI에서는 "$message.header#/correlationId" 같은 런타임 표현식으로 correlationId 위치를 정의하여 메시지 헤더의 correlationId 필드를 가리킵니다. 이를 통해 시스템이 비동기 응답을 원래 요청과 매칭할 수 있으며, Kafka 위의 비동기 RPC 같은 패턴에 필수적입니다.

traits를 사용해 여러 채널에서 메시지 정의를 재사용하는 방법은?

"components.messageTraits"에 공통 헤더 구조를 정의합니다. 예를 들어 분산 트레이싱을 위한 traceId 속성이 있는 commonHeaders trait를 만들 수 있습니다. 그런 다음 "traits: [{$ref: '#/components/messageTraits/commonHeaders'}]"로 개별 메시지 정의에서 trait를 참조합니다. trait 속성이 메시지 정의에 병합되어 여러 메시지 정의의 중복을 방지합니다.

AsyncAPI는 이벤트 기반 API의 OAuth2 보안을 어떻게 처리하나요?

components.securitySchemes에 적절한 flow 유형(서비스 간 통신에는 clientCredentials 등)의 oauth2 보안 체계를 정의합니다. tokenUrl을 지정하고 설명이 있는 스코프를 정의합니다. "security: [{$ref: '#/components/securitySchemes/oauth2'}]"로 서버에 보안을 적용하거나, 채널 수준 접근 제어를 위해 특정 채널에 적용합니다. Kafka 브로커 인증에는 SASL scramSha256을 사용합니다.

AsyncAPI 바인딩이란 무엇이며 언제 필요한가요?

바인딩은 일반 채널 또는 메시지 정의를 확장하는 프로토콜별 구성을 제공합니다. 특정 브로커에 배포할 때 필요합니다: Kafka 바인딩은 토픽 이름, 파티션 수, 복제 팩터를 설정하고, AMQP 바인딩은 큐 내구성과 독점성을 구성하며, MQTT 바인딩은 QoS 수준과 retain 플래그를 설정하고, WebSocket 바인딩은 HTTP 업그레이드 메서드와 쿼리 파라미터를 지정합니다.

페이로드가 여러 메시지 유형 중 하나일 수 있는 다형성 이벤트를 어떻게 문서화하나요?

페이로드 정의에 JSON Schema의 "oneOf" 또는 "anyOf"를 사용하고, 각 옵션은 components.schemas의 특정 메시지 스키마에 대한 $ref로 지정합니다. 예를 들어 OrderEvent 채널의 페이로드가 oneOf: OrderCreated와 OrderCancelled 스키마를 가질 수 있습니다. AsyncAPI 3.0 오퍼레이션의 "messages" 배열을 사용해 오퍼레이션이 처리하는 메시지 유형을 명시적으로 나열할 수도 있습니다.