7개 마이크로서비스 API 명세서 컨벤션 통일

- 공통 OpenAPI 3.0.3 컨벤션 문서 작성 (design/backend/api/API_CONVENTION.md) - 7개 서비스 API 명세서 표준화 완료: * User Service (8081) * Event Service (8080) * Content Service (8082) * AI Service (8083) * Participation Service (8084) * Distribution Service (8085) * Analytics Service (8086) 주요 변경사항: - API 경로에서 /api prefix 제거 (/api/users → /users) - 서버 URL 패턴 통일 (Local → Dev → Prod) - 연락처 정보 표준화 (Digital Garage Team) - ErrorResponse 스키마 통일 (error → message, details 추가) - securitySchemes 이름 통일 (BearerAuth) - 포트 번호 명확히 할당 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-06-13 11:39:11 +00:00 · 2025-10-23 17:12:28 +09:00
parent b9745f24e5
commit 6b1c4224f7
8 changed files with 1080 additions and 151 deletions
@@ -22,14 +22,12 @@ info:
    email: support@kt-event-marketing.com

 servers:
-  - url: https://api.kt-event-marketing.com/user/v1
-    description: Production Server
-  - url: https://dev-api.kt-event-marketing.com/user/v1
-    description: Development Server
-  - url: https://virtserver.swaggerhub.com/kt-event-marketing/user-service/1.0.0
-    description: SwaggerHub Mock Server
  - url: http://localhost:8081
    description: Local Development Server
+  - url: https://dev-api.kt-event-marketing.com/user/v1
+    description: Development Server
+  - url: https://api.kt-event-marketing.com/user/v1
+    description: Production Server

 tags:
  - name: Authentication
@@ -38,7 +36,7 @@ tags:
    description: 프로필 관련 API (조회, 수정, 비밀번호 변경)

 paths:
-  /api/users/register:
+  /users/register:
    post:
      tags:
        - Authentication
@@ -122,19 +120,19 @@ paths:
                  summary: 중복 사용자
                  value:
                    code: USER_001
-                    error: 이미 가입된 전화번호입니다
+                    message: 이미 가입된 전화번호입니다
                    timestamp: 2025-10-22T10:30:00Z
                invalidBusinessNumber:
                  summary: 사업자번호 검증 실패
                  value:
                    code: USER_002
-                    error: 유효하지 않은 사업자번호입니다. 휴폐업 여부를 확인해주세요.
+                    message: 유효하지 않은 사업자번호입니다. 휴폐업 여부를 확인해주세요.
                    timestamp: 2025-10-22T10:30:00Z
                validationError:
                  summary: 입력 검증 오류
                  value:
                    code: VALIDATION_ERROR
-                    error: 비밀번호는 8자 이상이어야 합니다
+                    message: 비밀번호는 8자 이상이어야 합니다
                    timestamp: 2025-10-22T10:30:00Z
        '500':
          description: 서버 오류
@@ -143,7 +141,7 @@ paths:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

-  /api/users/login:
+  /users/login:
    post:
      tags:
        - Authentication
@@ -205,10 +203,10 @@ paths:
                  summary: 인증 실패
                  value:
                    code: AUTH_001
-                    error: 전화번호 또는 비밀번호를 확인해주세요
+                    message: 전화번호 또는 비밀번호를 확인해주세요
                    timestamp: 2025-10-22T10:30:00Z

-  /api/users/logout:
+  /users/logout:
    post:
      tags:
        - Authentication
@@ -257,10 +255,10 @@ paths:
                  summary: 유효하지 않은 토큰
                  value:
                    code: AUTH_002
-                    error: 유효하지 않은 토큰입니다
+                    message: 유효하지 않은 토큰입니다
                    timestamp: 2025-10-22T10:30:00Z

-  /api/users/profile:
+  /users/profile:
    get:
      tags:
        - Profile
@@ -318,7 +316,7 @@ paths:
                  summary: 사용자 없음
                  value:
                    code: USER_003
-                    error: 사용자를 찾을 수 없습니다
+                    message: 사용자를 찾을 수 없습니다
                    timestamp: 2025-10-22T10:30:00Z

    put:
@@ -335,7 +333,7 @@ paths:
        - 매장 정보: 매장명, 업종, 주소, 영업시간

        **주의사항:**
-        - 비밀번호 변경은 별도 API 사용 (/api/users/password)
+        - 비밀번호 변경은 별도 API 사용 (/users/password)
        - 전화번호 변경 시 향후 재인증 필요 (현재는 직접 변경 가능)
        - Optimistic Locking으로 동시성 제어
      operationId: updateProfile
@@ -410,10 +408,10 @@ paths:
                  summary: 동시성 충돌
                  value:
                    code: USER_005
-                    error: 다른 세션에서 프로필을 수정했습니다. 새로고침 후 다시 시도하세요
+                    message: 다른 세션에서 프로필을 수정했습니다. 새로고침 후 다시 시도하세요
                    timestamp: 2025-10-22T10:30:00Z

-  /api/users/password:
+  /users/password:
    put:
      tags:
        - Profile
@@ -472,13 +470,13 @@ paths:
                  summary: 현재 비밀번호 불일치
                  value:
                    code: USER_004
-                    error: 현재 비밀번호가 일치하지 않습니다
+                    message: 현재 비밀번호가 일치하지 않습니다
                    timestamp: 2025-10-22T10:30:00Z
                invalidNewPassword:
                  summary: 새 비밀번호 규칙 위반
                  value:
                    code: VALIDATION_ERROR
-                    error: 비밀번호는 8자 이상이어야 하며 영문/숫자/특수문자를 포함해야 합니다
+                    message: 비밀번호는 8자 이상이어야 하며 영문/숫자/특수문자를 포함해야 합니다
                    timestamp: 2025-10-22T10:30:00Z
        '401':
          description: 인증 실패
@@ -487,7 +485,7 @@ paths:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

-  /api/users/{userId}/store:
+  /users/{userId}/store:
    get:
      tags:
        - Profile
@@ -547,7 +545,7 @@ paths:
                  summary: 인증 실패
                  value:
                    code: AUTH_002
-                    error: 유효하지 않은 토큰입니다
+                    message: 유효하지 않은 토큰입니다
                    timestamp: 2025-10-22T10:30:00Z
        '403':
          description: 권한 없음 (내부 서비스만 접근 가능)
@@ -560,7 +558,7 @@ paths:
                  summary: 권한 없음
                  value:
                    code: AUTH_003
-                    error: 이 API는 내부 서비스만 접근 가능합니다
+                    message: 이 API는 내부 서비스만 접근 가능합니다
                    timestamp: 2025-10-22T10:30:00Z
        '404':
          description: 사용자 또는 매장을 찾을 수 없음
@@ -573,7 +571,7 @@ paths:
                  summary: 사용자 또는 매장 없음
                  value:
                    code: USER_003
-                    error: 사용자 또는 매장을 찾을 수 없습니다
+                    message: 사용자 또는 매장을 찾을 수 없습니다
                    timestamp: 2025-10-22T10:30:00Z
        '500':
          description: 서버 오류
@@ -983,7 +981,7 @@ components:
      type: object
      required:
        - code
-        - error
+        - message
        - timestamp
      properties:
        code:
@@ -1000,7 +998,7 @@ components:
            - AUTH_002  # 유효하지 않은 토큰
            - AUTH_003  # 권한 없음 (내부 서비스만 접근)
            - VALIDATION_ERROR  # 입력 검증 오류
-        error:
+        message:
          type: string
          description: 에러 메시지
          example: 이미 가입된 전화번호입니다
@@ -1009,3 +1007,9 @@ components:
          format: date-time
          description: 에러 발생 시각
          example: 2025-10-22T10:30:00Z
+        details:
+          type: array
+          description: 상세 에러 정보 (선택 사항)
+          items:
+            type: string
+          example: ["필드명: 필수 항목입니다"]