01. WebSocket 이벤트 문서화

[davidpro08]

요약

Swagger로 나타낼 수 없는 WebSocket API를 Async Api 사용해서 나타내고 문서화

💡

날짜: 2026-01-05 / 상태: 보관

맥락

• 기존 Swagger는 Rest API만 보여주기 때문에 웹 소켓 API를 확인할 수 없었음

• 이에 따라 웹 소켓 API를 보여줄 수 있는 방법을 찾았음
• 방법은 3가지
  • Async API 사용 → 가장 표준
  • PostMan이나 Hoppscotch등의 데이터 저장 후 공유
  • Swagger에 읽기 전용으로 노출

결정

3가지 방법 중 Async API를 사용하는 것이 가장 좋다고 결론 내림

• PostMan을 사용하면 API가 변경될 때 마다 테스트를 하고 데이터를 저장한 뒤 공유해야 하는데, 이건 문서화가 아니고 번거롭다고 느껴졌음
• Swagger에 읽기 전용으로 노출시키는 건 실제 사용하는 API가 아니며 websocket 이벤트가 변경되면 귀찮게 변경시켜줘야 해서 안 좋다고 판단

Swagger에는 Rest API만 볼 수 있도록 하고 Websocket API는 Async API로 확인하기

트러블 슈팅

Async API 1.4.0 버전에서 내부 의존성으로 html-template를 의존함. 근데 여기서 react 예전 버전을 참조하고 있어서 버전 오류가 남.

Async API에서 react를 참조할 때 현재 프로젝트 버전 19.2.0을 참조하도록 override함

package.json

  "overrides": {
    "react": "^19.2.0",
    "react-dom": "^19.2.0",
    "@asyncapi/html-template": {
      "react": "^19.2.0",
      "react-dom": "^19.2.0"
    },
    "@asyncapi/generator": {
      "@asyncapi/html-template": {
        "react": "^19.2.0",
        "react-dom": "^19.2.0"
      }
    },
    "nestjs-asyncapi": {
      "@asyncapi/html-template": {
        "react": "^19.2.0",
        "react-dom": "^19.2.0"
      }
    }
  }

결과

Pros

• 이제 웹 소켓 이벤트 확인 가능

Cons

• 한번에 모든 내용을 한 사이트에서 볼 수는 없음

규정 준수

참고