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
@@ -41,15 +41,15 @@ info:
    - CDN URL 반환

  contact:
-    name: Content Service Team
-    email: content-team@kt.com
+    name: Digital Garage Team
+    email: support@kt-event-marketing.com

 servers:
-  - url: http://localhost:8083
-    description: Content Service Local Development Server
-  - url: https://api-dev.kt-event.com
+  - url: http://localhost:8082
+    description: Local Development Server
+  - url: https://dev-api.kt-event-marketing.com/content/v1
    description: Development Server
-  - url: https://api.kt-event.com
+  - url: https://api.kt-event-marketing.com/content/v1
    description: Production Server

 tags:
@@ -61,7 +61,7 @@ tags:
    description: 이미지 재생성 및 삭제 (UFR-CONT-020)

 paths:
-  /api/content/images/generate:
+  /content/images/generate:
    post:
      tags:
        - Job Status
@@ -71,7 +71,7 @@ paths:

        ## 처리 방식
        - **비동기 처리**: Kafka `image-generation-job` 토픽에 Job 발행
-        - **폴링 조회**: jobId로 생성 상태 조회 (GET /api/content/images/jobs/{jobId})
+        - **폴링 조회**: jobId로 생성 상태 조회 (GET /content/images/jobs/{jobId})
        - **캐싱**: 동일한 eventDraftId 재요청 시 캐시 반환 (TTL 7일)

        ## 생성 스타일
@@ -91,7 +91,7 @@ paths:
        content:
          application/json:
            schema:
-              $ref: '#/components/schemas/ImageGenerationRequest'
+              $ref: "#/components/schemas/ImageGenerationRequest"
            examples:
              basicEvent:
                summary: 기본 이벤트
@@ -112,14 +112,14 @@ paths:
                    brandColor: "#00704A"

      responses:
-        '202':
+        "202":
          description: |
            이미지 생성 요청이 성공적으로 접수되었습니다.
            jobId를 사용하여 생성 상태를 폴링 조회하세요.
          content:
            application/json:
              schema:
-                $ref: '#/components/schemas/ImageGenerationAcceptedResponse'
+                $ref: "#/components/schemas/ImageGenerationAcceptedResponse"
              examples:
                accepted:
                  summary: 요청 접수 성공
@@ -130,12 +130,12 @@ paths:
                    estimatedCompletionTime: 5
                    message: "이미지 생성 요청이 접수되었습니다. jobId로 결과를 조회하세요."

-        '400':
+        "400":
          description: 잘못된 요청 (필수 필드 누락, 유효하지 않은 데이터)
          content:
            application/json:
              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+                $ref: "#/components/schemas/ErrorResponse"
              examples:
                missingField:
                  summary: 필수 필드 누락
@@ -150,12 +150,12 @@ paths:
                    message: "brandColor는 HEX 색상 코드 형식이어야 합니다."
                    timestamp: "2025-10-22T14:30:00Z"

-        '429':
+        "429":
          description: 요청 제한 초과 (Rate Limiting)
          content:
            application/json:
              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+                $ref: "#/components/schemas/ErrorResponse"
              examples:
                rateLimitExceeded:
                  summary: 요청 제한 초과
@@ -165,12 +165,12 @@ paths:
                    timestamp: "2025-10-22T14:30:00Z"
                    retryAfter: 60

-        '500':
+        "500":
          description: 서버 내부 오류
          content:
            application/json:
              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+                $ref: "#/components/schemas/ErrorResponse"
              examples:
                internalError:
                  summary: 서버 내부 오류
@@ -182,7 +182,7 @@ paths:
      security:
        - BearerAuth: []

-  /api/content/images/jobs/{jobId}:
+  /content/images/jobs/{jobId}:
    get:
      tags:
        - Job Status
@@ -218,12 +218,12 @@ paths:
            example: "job-img-abc123"

      responses:
-        '200':
+        "200":
          description: 이미지 생성 상태 조회 성공
          content:
            application/json:
              schema:
-                $ref: '#/components/schemas/ImageGenerationStatusResponse'
+                $ref: "#/components/schemas/ImageGenerationStatusResponse"
              examples:
                pending:
                  summary: 대기 중
@@ -308,12 +308,12 @@ paths:
                      detail: "외부 AI API 응답 시간 초과. 기본 템플릿으로 대체되었습니다."
                    completedAt: "2025-10-22T14:30:25Z"

-        '404':
+        "404":
          description: Job ID를 찾을 수 없음
          content:
            application/json:
              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+                $ref: "#/components/schemas/ErrorResponse"
              examples:
                notFound:
                  summary: Job ID 없음
@@ -322,12 +322,12 @@ paths:
                    message: "Job ID를 찾을 수 없습니다."
                    timestamp: "2025-10-22T14:30:00Z"

-        '500':
+        "500":
          description: 서버 내부 오류
          content:
            application/json:
              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+                $ref: "#/components/schemas/ErrorResponse"
              examples:
                internalError:
                  summary: 서버 내부 오류
@@ -339,7 +339,7 @@ paths:
      security:
        - BearerAuth: []

-  /api/content/events/{eventDraftId}:
+  /content/events/{eventDraftId}:
    get:
      tags:
        - Content Management
@@ -363,12 +363,12 @@ paths:
            example: "evt-draft-12345"

      responses:
-        '200':
+        "200":
          description: 콘텐츠 조회 성공
          content:
            application/json:
              schema:
-                $ref: '#/components/schemas/ContentResponse'
+                $ref: "#/components/schemas/ContentResponse"
              examples:
                success:
                  summary: 콘텐츠 조회 성공
@@ -403,12 +403,12 @@ paths:
                    createdAt: "2025-10-22T14:30:00Z"
                    expiresAt: "2025-10-29T14:30:00Z"

-        '404':
+        "404":
          description: 콘텐츠를 찾을 수 없음 (생성 중이거나 만료됨)
          content:
            application/json:
              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+                $ref: "#/components/schemas/ErrorResponse"
              examples:
                notFound:
                  summary: 콘텐츠 없음
@@ -417,17 +417,17 @@ paths:
                    message: "해당 이벤트의 콘텐츠를 찾을 수 없습니다."
                    timestamp: "2025-10-22T14:30:00Z"

-        '500':
+        "500":
          description: 서버 내부 오류
          content:
            application/json:
              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+                $ref: "#/components/schemas/ErrorResponse"

      security:
        - BearerAuth: []

-  /api/content/events/{eventDraftId}/images:
+  /content/events/{eventDraftId}/images:
    get:
      tags:
        - Content Management
@@ -465,7 +465,7 @@ paths:
            example: "INSTAGRAM"

      responses:
-        '200':
+        "200":
          description: 이미지 목록 조회 성공
          content:
            application/json:
@@ -479,7 +479,7 @@ paths:
                  images:
                    type: array
                    items:
-                      $ref: '#/components/schemas/GeneratedImage'
+                      $ref: "#/components/schemas/GeneratedImage"
              examples:
                allImages:
                  summary: 전체 이미지 조회
@@ -496,17 +496,17 @@ paths:
                          height: 1080
                        createdAt: "2025-10-22T14:30:05Z"

-        '404':
+        "404":
          description: 이미지를 찾을 수 없음
          content:
            application/json:
              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+                $ref: "#/components/schemas/ErrorResponse"

      security:
        - BearerAuth: []

-  /api/content/images/{imageId}:
+  /content/images/{imageId}:
    get:
      tags:
        - Image Management
@@ -526,12 +526,12 @@ paths:
            example: "img-12345-simple"

      responses:
-        '200':
+        "200":
          description: 이미지 조회 성공
          content:
            application/json:
              schema:
-                $ref: '#/components/schemas/GeneratedImage'
+                $ref: "#/components/schemas/GeneratedImage"
              examples:
                success:
                  summary: 이미지 조회 성공
@@ -545,12 +545,12 @@ paths:
                      height: 1080
                    createdAt: "2025-10-22T14:30:05Z"

-        '404':
+        "404":
          description: 이미지를 찾을 수 없음
          content:
            application/json:
              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+                $ref: "#/components/schemas/ErrorResponse"

      security:
        - BearerAuth: []
@@ -577,20 +577,20 @@ paths:
            example: "img-12345-simple"

      responses:
-        '204':
+        "204":
          description: 이미지 삭제 성공

-        '404':
+        "404":
          description: 이미지를 찾을 수 없음
          content:
            application/json:
              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+                $ref: "#/components/schemas/ErrorResponse"

      security:
        - BearerAuth: []

-  /api/content/images/{imageId}/regenerate:
+  /content/images/{imageId}/regenerate:
    post:
      tags:
        - Image Management
@@ -619,7 +619,7 @@ paths:
        content:
          application/json:
            schema:
-              $ref: '#/components/schemas/ImageRegenerationRequest'
+              $ref: "#/components/schemas/ImageRegenerationRequest"
            examples:
              modifyPrompt:
                summary: 프롬프트 수정
@@ -631,7 +631,7 @@ paths:
                  style: "FANCY"

      responses:
-        '202':
+        "202":
          description: 재생성 요청 접수 (비동기 처리)
          content:
            application/json:
@@ -653,19 +653,19 @@ paths:
                    description: 예상 소요 시간 (초)
                    example: 10

-        '404':
+        "404":
          description: 원본 이미지를 찾을 수 없음
          content:
            application/json:
              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+                $ref: "#/components/schemas/ErrorResponse"

-        '503':
+        "503":
          description: 이미지 생성 서비스 장애 (Circuit Breaker Open)
          content:
            application/json:
              schema:
-                $ref: '#/components/schemas/CircuitBreakerErrorResponse'
+                $ref: "#/components/schemas/CircuitBreakerErrorResponse"

      security:
        - BearerAuth: []
@@ -723,7 +723,7 @@ components:
            brandColor:
              type: string
              description: 브랜드 컬러 (HEX)
-              pattern: '^#[0-9A-Fa-f]{6}$'
+              pattern: "^#[0-9A-Fa-f]{6}$"
              example: "#FF5733"
            logoUrl:
              type: string
@@ -801,7 +801,7 @@ components:
              description: |
                브랜드 컬러 (HEX 색상 코드)
                사용자 프로필에서 가져오거나 기본값 사용
-              pattern: '^#[0-9A-Fa-f]{6}$'
+              pattern: "^#[0-9A-Fa-f]{6}$"
              example: "#FF5733"

            logoUrl:
@@ -883,7 +883,7 @@ components:
          type: array
          description: 생성된 이미지 배열 (COMPLETED 상태에서만)
          items:
-            $ref: '#/components/schemas/GeneratedImage'
+            $ref: "#/components/schemas/GeneratedImage"

        completedAt:
          type: string
@@ -897,7 +897,7 @@ components:
          example: false

        error:
-          $ref: '#/components/schemas/JobError'
+          $ref: "#/components/schemas/JobError"

    GeneratedImage:
      type: object
@@ -1016,7 +1016,7 @@ components:
          type: array
          description: 생성된 이미지 목록
          items:
-            $ref: '#/components/schemas/ImageDetail'
+            $ref: "#/components/schemas/ImageDetail"

        totalCount:
          type: integer