feat(api-doc): add OpenAPI 3.1.0 + AsyncAPI 3.0.0 + Redoc UI with CI validation

[ppzxc]

Summary

• internal/apidocs/ 패키지: OpenAPI 3.1.0 + AsyncAPI 3.0.0 스펙 파일 + Redoc v2 standalone JS 바이너리 embed
• /docs, /docs/openapi, /docs/asyncapi HTTP 엔드포인트 추가 (chi 라우터 통합)
• GitHub Actions CI: Spectral lint + AsyncAPI validate (스펙 파일 변경 시 자동 실행)

Motivation

단일 바이너리에 문서 UI를 포함해 외부 CDN 의존 없이 API 문서를 서빙한다.
구현된 엔드포인트와 계획 중인 엔드포인트(x-status: planned)를 모두 문서화했다.

Changes

• internal/apidocs/embed.go — //go:embed 선언 + 3개 HTTP 핸들러
• internal/apidocs/openapi.yaml — OpenAPI 3.1.0 (9개 엔드포인트, 3개 구현 + 6개 planned)
• internal/apidocs/asyncapi.yaml — AsyncAPI 3.0.0 (WebSocket 인바운드 채널)
• internal/apidocs/redoc.standalone.js — Redoc v2.1.5 standalone bundle (~887KB)
• internal/apidocs/embed_test.go — 핸들러 유닛 테스트
• internal/adapter/input/http/router.go — /docs 라우트 그룹 추가
• internal/adapter/input/http/handler_test.go — docs 엔드포인트 통합 테스트
• .spectral.yaml — OAS 3.1 ruleset (oas3-schema: error)
• .github/workflows/api-doc.yml — Spectral @6.15.0 + AsyncAPI CLI @3.6.0 검증 워크플로

Test plan

• go test -race ./internal/apidocs/... ./internal/adapter/input/http/... 통과 확인
• go build -o webhook-relay ./cmd/server/ 빌드 성공 확인
• 서버 실행 후 curl http://localhost:8080/docs → Redoc HTML 응답 확인
• curl http://localhost:8080/docs/openapi → OpenAPI YAML 응답 확인
• GitHub Actions api-doc.yml 워크플로 통과 확인

[ppzxc]

전체적으로 스펙에 충실하고 불필요한 코드 없이 목적에 맞게 구현되어 있다.

긍정적인 점:

• embed.go — 핸들러가 각 10줄 이하로 단순하고 명확. //nolint:errcheck 주석은 ResponseWriter.Write() 에러 무시의 의도를 명확히 표현
• router.go — /docs 라우트가 auth 미들웨어 바깥에 등록 (공개 엔드포인트로 올바름)
• embed_test.go — black-box 테스트 패키지(apidocs_test), Content-Type + body 내용까지 검증
• openapi.yaml — security: [] 로 /healthz override, x-status: planned 으로 미구현 엔드포인트 표시
• asyncapi.yaml — action: receive (서버 수신 방향 정확), additionalProperties: true (다형적 페이로드 허용)
• GitHub Actions — permissions: contents: read 최소 권한, 버전 핀 고정

마이너 관찰 (비차단):

• embed_test.go:26 — // placeholder는 version "0.0.0" 주석은 TDD 개발 흔적. 현재 코드와 맞지 않아 혼란을 줄 수 있으나 기능에 영향 없음
• AsyncAPI CI가 아직 pending — 결과 확인 후 머지 권장