swagger.yaml

swagger: '2.0'
info:
  description: 라이블 API
  version: 1.0.0
  title: Livle App API
host: api.livle.kr
basePath: /dev
tags:
  - name: user
    description: 라이블 일반 회원 (앱)
  - name: partner
    description: 공연기획사 회원 (웹)
  - name: ticket
    description: 콘서트 정보
  - name: reservation
    description: '콘서트 예약 정보 [미구현]'
  - name: subscription
    description: 구독 정보
  - name: file
    description: 파일 관리
schemes:
  - https
paths:
  /user:
    post:
      tags:
        - user
      summary: 회원가입
      description: '이메일, 비밀번호 validation은 클라이언트에서 해주세요.'
      consumes:
        - application/json
      parameters:
        - name: user
          in: body
          description: 가입할 유저의 아이디와 비밀번호
          required: true
          schema:
            type: object
            properties:
              email:
                type: string
                example: contacts@livle.kr
              password:
                type: string
                example: '12345'
              nickname:
                type: string
                example: 라이블
                description: optional
              fcmToken:
                type: string
                description: 푸시 알림을 보내기 위한 기기 식별토큰
      responses:
        '200':
          description: 가입 성공
          schema:
            $ref: '#/definitions/UserSession'
        '400':
          description: 잘못된 요청 (이메일이나 비밀번호가 없음)
        '403':
          description: 이미 존재하는 아이디
        '404':
          description: 존재하지 않는 이메일 주소
        '405':
          description: 잘못된 이메일 형식
    delete:
      tags:
        - user
      summary: 탈퇴
      description: '이메일, 비밀번호 validation은 클라이언트에서 해주세요.'
      consumes:
        - application/json
      parameters:
        - name: user
          in: body
          description: 탈퇴할 유저의 아이디와 비밀번호
          required: true
          schema:
            type: object
            properties:
              email:
                type: string
                example: contacts@livle.kr
              password:
                type: string
                example: '12345'
      responses:
        '200':
          description: 탈퇴 성공
        '400':
          description: 잘못된 요청 (이메일이나 비밀번호가 없음)
        '403':
          description: 비밀번호가 틀립니다.
        '404':
          description: 해당 이메일의 유저가 없습니다.
        '405':
          description: 구독 중인 유저입니다. 탈퇴 전에 구독을 취소해야 합니다.
    get:
      tags:
        - user
      summary: 회원정보 가져오기
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: Authorization
          in: header
          type: string
          description: JWT Token
          required: true
        - name: fcmToken
          in: query
          description: 현재 기기의 fcm 토큰
          required: true
          type: string
      responses:
        '200':
          description: 성공
          schema:
            $ref: '#/definitions/UserData'
        '401':
          description: 헤더에 토큰이 없음
        '403':
          description: 헤더에 토큰이 있지만 유효하지 않음
  /user/facebook:
    post:
      tags:
        - user
      summary: 페이스북 가입 / 로그인
      parameters:
        - name: accessToken
          in: body
          required: true
          schema:
            type: object
            properties:
              accessToken:
                type: string
              fcmToken:
                type: string
                description: 푸시 알림을 보내기 위한 기기 식별토큰
      responses:
        '200':
          description: '기존 계정을 발견, 로그인'
          schema:
            $ref: '#/definitions/UserSession'
        '201':
          description: '기존 유저가 아님, 신규가입됨'
          schema:
            $ref: '#/definitions/UserSession'
        '400':
          description: access_token이 없음
        '401':
          description: access_token이 유효하지 않음
        '403':
          description: 이메일로 가입한 내용이 있음. 이메일로 로그인할 것
  /user/password:
    get:
      tags:
        - user
      summary: 비밀번호 재설정 이메일 보내기
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: email
          in: query
          description: 비밀번호를 재설정할 이메일
          required: true
          type: string
      responses:
        '200':
          description: 이메일 전송
        '400':
          description: 이메일이 없거나 잘못된 형식
        '404':
          description: 해당하는 유저가 없음
    post:
      tags:
        - user
      summary: 비밀번호 재설정하기
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: params
          in: body
          schema:
            type: object
            properties:
              password:
                type: string
                example: abcde
                description: 새로운 비밀번호
              token:
                type: string
                example: f7QdxGje
                description: 이메일에 포함된 비밀번호 변경 토큰
      responses:
        '200':
          description: 변경 성공
        '400':
          description: 비밀번호나 토큰이 없음
        '404':
          description: 잘못된 토큰
  /user/session:
    post:
      tags:
        - user
      summary: 로그인
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: user
          in: body
          description: 로그인할 유저의 아이디와 비밀번호
          required: true
          schema:
            type: object
            properties:
              email:
                type: string
                example: contacts@livle.kr
              password:
                type: string
                example: '12345'
              fcmToken:
                type: string
                description: 푸시 알림을 보내기 위한 기기 식별토큰
      responses:
        '200':
          description: 로그인 성공
          schema:
            $ref: '#/definitions/UserSession'
        '400':
          description: 이메일 또는 비밀번호가 없거나 잘못됨
        '403':
          description: 해당 아이디로 가입된 정보는 있으나 비밀번호가 틀림
        '404':
          description: 해당 아이디로 가입된 정보가 없음
    delete:
      tags:
        - user
      summary: 로그아웃 - Session Storage 이용하지 않으므로 불필요
      responses:
        '200':
          description: 로그아웃 성공
  /user/list:
    get:
      tags:
        - user
      summary: '모든 회원정보 가져오기 [관리자]'
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: Authorization
          in: header
          type: string
          description: 관리자의 Partner 계정의 토큰입니다.
          required: true
        - name: page
          in: query
          type: string
          required: true
        - name: email
          in: query
          type: string
      responses:
        '200':
          description: 성공
          schema:
            type: object
            properties:
              total_pages:
                type: integer
                example: 10
              current_page:
                type: integer
                example: 1
              data:
                type: array
                items:
                  $ref: '#/definitions/UserData'
        '401':
          description: 헤더에 토큰이 없음
        '403':
          description: 헤더에 토큰이 있지만 유효하지 않음
  '/user/{userId}/suspend':
    delete:
      tags:
        - user
      summary: '[관리자] 유저 이용정지 해제하기'
      parameters:
        - name: Authorization
          in: header
          type: string
          description: 관리자의 Partner 계정의 토큰입니다.
          required: true
        - name: userId
          in: path
          required: true
          type: integer
          format: int64
      responses:
        '200':
          description: '성공, 상세 구독 정보는 제외하고 리턴됩니다'
          schema:
            $ref: '#/definitions/UserData'
        '401':
          description: 로그인되지 않음
        '403':
          description: 권한이 없음
  /partner:
    post:
      tags:
        - partner
      summary: 회원가입
      description: '이메일, 비밀번호 validation은 클라이언트에서 해주세요.'
      consumes:
        - application/json
      parameters:
        - name: partner
          in: body
          description: 가입할 유저의 아이디와 비밀번호
          required: true
          schema:
            type: object
            properties:
              company:
                type: string
                example: 라이블
              username:
                type: string
                example: livle
              password:
                type: string
                example: '12345'
      responses:
        '200':
          description: 가입 성공
          schema:
            $ref: '#/definitions/Partner'
        '400':
          description: 잘못된 요청 (이메일이나 비밀번호가 없음)
        '403':
          description: 이미 존재하는 아이디
        '405':
          description: 잘못된 이메일 형식
    get:
      tags:
        - partner
      summary: 세션 체크
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: Authorization
          in: header
          description: 세션 정보를 담고 있는 토큰
          required: true
          type: string
      responses:
        '200':
          description: 로그인된 유저
          schema:
            $ref: '#/definitions/Partner'
        '401':
          description: 로그인되지 않은 상태
        '403':
          description: 유효하지 않은 세션
  /partner/session:
    post:
      tags:
        - partner
      summary: 로그인
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: body
          in: body
          schema:
            type: object
            properties:
              username:
                type: string
                example: contacts@livle.kr
              password:
                type: string
                example: '12345'
      responses:
        '200':
          description: 로그인 성공
          schema:
            $ref: '#/definitions/Partner'
        '400':
          description: 이메일 또는 비밀번호가 없거나 잘못됨
        '401':
          description: 아직 승인되지 않은 계정임
        '403':
          description: 일치하는 회원이 없음
  /partner/list:
    get:
      tags:
        - partner
      summary: '모든 파트너 정보 [관리자]'
      consumes:
        - application/json
      parameters:
        - name: Authorization
          in: header
          description: 세션 정보를 담고 있는 토큰
          required: true
          type: string
        - name: page
          in: query
          type: string
          required: true
        - name: username
          in: query
          type: string
        - name: company
          in: query
          type: string
        - name: approved
          in: query
          type: string
          description: true | false
      responses:
        '200':
          description: 성공
          schema:
            type: object
            properties:
              total_pages:
                type: integer
                example: 10
              current_page:
                type: integer
                example: 1
              data:
                type: array
                items:
                  $ref: '#/definitions/Partner'
        '401':
          description: 헤더에 토큰이 없음
        '403':
          description: 헤더에 토큰이 있지만 유효하지 않음
  '/partner/{partnerId}/approve':
    post:
      tags:
        - partner
      summary: '파트너 가입 승인 [관리자]'
      parameters:
        - name: partnerId
          in: path
          required: true
          type: integer
          format: int64
        - name: Authorization
          in: header
          description: 세션 정보를 담고 있는 토큰
          required: true
          type: string
      responses:
        '200':
          description: 성공
          schema:
            $ref: '#/definitions/Partner'
        '401':
          description: 헤더에 토큰이 없음
        '403':
          description: 헤더에 토큰이 있지만 유효하지 않거나 권한이 없음
  /ticket:
    get:
      tags:
        - ticket
      summary: 일주일 간의 티켓 정보 가져오기
      produces:
        - application/json
      responses:
        '200':
          description: 성공
          schema:
            type: array
            items:
              $ref: '#/definitions/Ticket'
    post:
      tags:
        - ticket
      summary: '[관리자] 새로운 티켓 등록하기'
      parameters:
        - name: Authorization
          in: header
          description: 세션 정보를 담고 있는 토큰
          required: true
          type: string
        - name: ticket
          in: body
          required: true
          description: >-
            Required: partner_id, title, start_at, end_at, image, capacity /
            Forbidden: id와 reservations는 없어야 합니다.
          schema:
            $ref: '#/definitions/TicketDetail'
      responses:
        '200':
          description: 성공
          schema:
            $ref: '#/definitions/Ticket'
        '401':
          description: 로그인되지 않음
        '403':
          description: 관리자가 아님
  '/ticket/{ticketId}':
    patch:
      tags:
        - ticket
      summary: '[관리자] 등록된 티켓 정보 수정하기'
      parameters:
        - name: Authorization
          in: header
          description: 세션 정보를 담고 있는 토큰
          required: true
          type: string
        - name: ticketId
          in: path
          required: true
          type: integer
          format: int64
        - name: ticket
          in: body
          required: true
          schema:
            $ref: '#/definitions/Ticket'
      responses:
        '200':
          description: 성공
          schema:
            $ref: '#/definitions/Ticket'
        '401':
          description: 로그인되지 않음
        '403':
          description: 관리자가 아님
    delete:
      tags:
        - ticket
      summary: '[관리자] 등록된 티켓 정보 삭제하기'
      parameters:
        - name: Authorization
          in: header
          description: 세션 정보를 담고 있는 토큰
          required: true
          type: string
        - name: ticketId
          in: path
          required: true
          type: integer
          format: int64
      responses:
        '200':
          description: 성공
        '401':
          description: 로그인되지 않음
        '403':
          description: 관리자가 아님
        '405':
          description: 이 공연의 취소되지 않은 예약이 남아있음
  '/ticket/{ticketId}/stats':
    get:
      tags:
        - ticket
      summary: (파트너) 티켓 하나의 상세 정보
      parameters:
        - name: Authorization
          in: header
          description: 세션 정보를 담고 있는 토큰
          required: true
          type: string
        - name: ticketId
          in: path
          required: true
          type: integer
          format: int64
      responses:
        '200':
          description: 성공
          schema:
            $ref: '#/definitions/TicketDetail'
        '401':
          description: 로그인되지 않음 (세션토큰이 없음)
        '403':
          description: 권한이 없음
        '404':
          description: 해당 아이디의 공연을 찾을 수 없음
  '/ticket/{ticketId}/reserve':
    post:
      tags:
        - ticket
      summary: 티켓 예약하기
      produces:
        - application/json
      parameters:
        - name: Authorization
          in: header
          description: 세션 정보를 담고 있는 토큰
          required: true
          type: string
        - name: ticketId
          in: path
          description: 예약할 티켓 아이디
          required: true
          type: integer
          format: int64
      responses:
        '200':
          description: 예약 성공
          schema:
            $ref: '#/definitions/Reservation'
        '400':
          description: 이미 시작한 공연
        '403':
          description: 구독 중인 유저가 아니거나 패널티를 받고 있음
        '404':
          description: 해당 티켓을 찾을 수 없음
        '405':
          description: >-
            예약 실패 (case 1) 이미 예약한 공연 (case 2) 잔여 좌석이 없음 (case 3) 예약 기회가 소진됨 (기간
            내에 2개 예약함)
  /ticket/list:
    get:
      tags:
        - ticket
      summary: (파트너) 티켓 정보 가져오기
      description: >-
        관리자의 경우 partnerId 쿼리를 설정하지 않으면 모든 티켓 정보를 가져오고, 설정하는 경우 해당 파트너의 티켓 정보를
        가져옵니다. 파트너의 경우 자신의 티켓 정보를 가져오며, partnerId를 설정하는 경우 403 에러를 반환합니다.
      parameters:
        - name: Authorization
          in: header
          description: 세션토큰
          required: true
          type: string
        - name: page
          in: query
          type: string
          required: true
        - name: parnterId
          in: query
          type: string
          description: 관리자만 설정할 수 있습니다. 관리자가 아닌데 설정한 경우 403 에러
        - name: title
          in: query
          type: string
        - name: state
          in: query
          type: string
          description: due | end
      responses:
        '200':
          description: 성공
          schema:
            type: object
            properties:
              total_pages:
                type: integer
                example: 10
              current_page:
                type: integer
                example: 1
              data:
                type: array
                items:
                  $ref: '#/definitions/Ticket'
        '401':
          description: 로그인되지 않음
  /reservation:
    get:
      tags:
        - reservation
      summary: 예약 정보 가져오기
      description: '입장된 것, 미입장된 것 모두 가져옵니다. checked_at이 null이면 아직 미입장.'
      parameters:
        - name: Authorization
          in: header
          description: 세션토큰
          required: true
          type: string
      responses:
        '200':
          description: 성공
          schema:
            type: array
            items:
              $ref: '#/definitions/Reservation'
        '401':
          description: 로그인되지 않음
  '/reservation/{reservationId}':
    delete:
      tags:
        - reservation
      summary: 예약 취소하기
      parameters:
        - name: reservationId
          in: path
          description: 예약 아이디
          required: true
          type: integer
          format: int64
        - name: Authorization
          in: header
          description: 세션토큰
          required: true
          type: string
      responses:
        '200':
          description: 성공
        '401':
          description: 로그인되지 않음
        '403':
          description: 공연 시작까지 4시간보다 적게 남음
        '404':
          description: 잘못된 예약 아이디이거나 이 유저의 예약이 아님
        '405':
          description: 이미 체크인처리가 된 예약
  '/reservation/{reservationId}/check':
    post:
      tags:
        - reservation
      summary: 체크인하기
      parameters:
        - name: reservationId
          in: path
          description: 예약 아이디
          required: true
          type: integer
          format: int64
        - name: Authorization
          in: header
          description: 세션토큰
          required: true
          type: string
        - name: code
          in: body
          required: true
          schema:
            type: object
            properties:
              code:
                type: string
                example: '1234'
      responses:
        '200':
          description: 체크인 성공
          schema:
            $ref: '#/definitions/Reservation'
        '400':
          description: 요청에 코드가 없음
        '401':
          description: 로그인되지 않음
        '403':
          description: 잘못된 체크인 코드
        '404':
          description: 잘못된 예약 아이디이거나 이 유저의 예약이 아님
        '405':
          description: 이미 체크인 함
  /subscription:
    post:
      tags:
        - subscription
      summary: 구독
      description: 결제 Validation 등
      parameters:
        - name: Authorization
          in: header
          description: 세션토큰
          required: true
          type: string
        - name: payment
          in: body
          required: true
          schema:
            $ref: '#/definitions/PaymentParams'
      responses:
        '200':
          description: 구독 성공
          schema:
            $ref: '#/definitions/UserData'
        '400':
          description: 결제 정보 중 누락된 것이 있음
        '401':
          description: 로그인되지 않음
        '402':
          description: 결제 정보 인증은 되었으나 결제 실패
        '403':
          description: 결제 정보 인증에 실패
        '405':
          description: 이미 구독 중
        '406':
          description: 이미 무료 체험을 시도한 카드
    patch:
      tags:
        - subscription
      summary: 구독 정보 변경
      parameters:
        - name: Authorization
          in: header
          description: 세션토큰
          required: true
          type: string
        - name: payment
          in: body
          required: true
          schema:
            $ref: '#/definitions/PaymentParams'
      responses:
        '200':
          description: '업데이트 성공, 결제는 이루어지지 않음'
          schema:
            $ref: '#/definitions/UserData'
        '201':
          description: '업데이트 성공, 결제 실패 내용 결제됨'
          schema:
            $ref: '#/definitions/UserData'
        '400':
          description: 결제 정보 중 누락된 것이 있음
        '401':
          description: 로그인되지 않음
        '402':
          description: 결제 정보 인증은 되었으나 결제 실패
        '403':
          description: 결제 정보 인증에 실패
        '404':
          description: 구독 중이 아님
    delete:
      tags:
        - subscription
      summary: 구독 취소
      parameters:
        - name: Authorization
          in: header
          description: 세션토큰
          required: true
          type: string
      responses:
        '200':
          description: 구독 취소 성공
          schema:
            $ref: '#/definitions/UserData'
        '401':
          description: 로그인되지 않음
        '404':
          description: 구독 중인 내역이 없음
  /subscription/restore:
    post:
      tags:
        - subscription
      summary: 취소한 구독을 복원
      parameters:
        - name: Authorization
          in: header
          description: 세션토큰
          required: true
          type: string
      responses:
        '200':
          description: '업데이트 성공, 결제는 이루어지지 않음'
          schema:
            $ref: '#/definitions/UserData'
        '401':
          description: 로그인되지 않음
        '403':
          description: 복구할 수 있는 상태가 아님 (미납이거나 취소한 적이 없음)
        '404':
          description: 복구할 구독이 없음
  '/subscription/{subscriptionId}/limit':
    patch:
      tags:
        - subscription
      summary: '[관리자] 유저의 예약 가능 횟수를 변경'
      parameters:
        - name: Authorization
          in: header
          description: 세션토큰
          required: true
          type: string
        - name: subscriptionId
          in: path
          required: true
          type: string
        - name: limit
          in: body
          required: true
          schema:
            type: object
            properties:
              limit:
                type: integer
                example: 3
      responses:
        '200':
          description: 업데이트 성공
        '401':
          description: 로그인되어 있지 않음
        '403':
          description: 권한이 없음
  /file:
    get:
      tags:
        - file
      summary: S3에 업로드하기 위해 인증
      parameters:
        - name: Authorization
          in: header
          description: 세션 정보를 담고 있는 토큰
          required: true
          type: string
      responses:
        '200':
          description: 인증됨
          schema:
            type: object
            properties:
              signedUrl:
                type: string
                description: 파일을 업로드할 action의 주소
                example: 'https://livle.s3.aws.com/upload/token12345'
              filePath:
                type: string
                description: 업로드될 파일 주소
                example: >-
                  https://s3.ap-northeast-2.amazonaws.com/livle/55b48f00-cf71-11e7-b3f4-ddd786cc1c81
        '401':
          description: 로그인되지 않음
        '403':
          description: 권한이 없음 (admin@livle.kr만 가능)
definitions:
  UserSession:
    type: object
    properties:
      email:
        type: string
        example: test@test.com
      nickname:
        type: string
        example: 라이블
      token:
        type: string
        description: >-
          회원가입 또는 로그인 시에만 전달됨. 클라이언트에 저장해두고 요청보낼 때 header에 Authorization이라는 이름으로
          포함하기.
  UserData:
    type: object
    properties:
      email:
        type: string
        example: test@test.com
      nickname:
        type: string
        example: 라이블
      cardName:
        type: string
        example: 신한카드
      lastFourDigits:
        type: string
        example: '1234'
        description: 카드 마지막 4자리
      suspendedBy:
        type: string
        description: 패널티로 라이블을 이용할 수 없는 기간
      freeTrial:
        type: object
        properties:
          createdAt:
            type: string
        description: '무료 체험 일련번호, 체험한 적이 없으면 null'
      currentSubscription:
        $ref: '#/definitions/Subscription'
      nextSubscription:
        $ref: '#/definitions/Subscription'
  Subscription:
    type: object
    properties:
      from:
        type: string
        example: '2018-01-03T15:00:00.467Z'
        description: 이 구독 유효기간의 시작
      to:
        type: string
        example: '2018-01-10T14:59:59.467Z'
        description: 이 구독 유효기간의 끝
      paidAt:
        type: string
        example: '2018-01-04T10:12:20.467Z'
        description: '결제가 이루어진 시기, 결제 예정 구독의 경우 null'
      used:
        type: integer
        format: int64
        example: 1
        description: 이 기간 동안 예약된 공연의 수
  Partner:
    type: object
    description: password는 리턴되지 않음
    properties:
      id:
        type: integer
        format: int64
      username:
        type: string
      company:
        type: string
      token:
        type: string
      approved:
        type: boolean
  Artist:
    type: object
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
      image:
        type: string
  TicketDetail:
    type: object
    properties:
      id:
        type: integer
        format: int64
      partner_id:
        type: integer
        format: int64
        description: 이 공연의 사장님 아이디
      title:
        type: string
        example: 댕댕이 페스티벌
      artists:
        type: array
        items:
          $ref: '#/definitions/Artist'
      start_at:
        type: number
        description: 시작시간
      end_at:
        type: number
        description: 종료시간
      image:
        type: string
        description: 카드 메인 이미지 주소
      capacity:
        type: number
        description: 예약할 수 있는 전체 좌석 수
      place:
        type: string
        example: 판교 스타트업캠퍼스
      video_id:
        type: string
        description: 영상 주소나 아이디... 아직 모름
      reservations:
        type: array
        items:
          $ref: '#/definitions/Reservation'
  Ticket:
    type: object
    properties:
      id:
        type: integer
        format: int64
      title:
        type: string
        example: 댕댕이 페스티벌
      artists:
        type: array
        items:
          $ref: '#/definitions/Artist'
      startAt:
        type: string
        description: 시작시간
      endAt:
        type: string
        description: 종료시간
      image:
        type: string
        description: 카드 메인 이미지 주소
      vacancies:
        type: number
        description: 남은 좌석 수
      place:
        type: string
        example: 판교 스타트업캠퍼스
      videoId:
        type: string
        description: 동영상 ID
  Reservation:
    type: object
    properties:
      id:
        type: integer
        format: int64
      user:
        type: object
        description: 파트너 페이지에서만 오는 데이터
        properties:
          email:
            type: string
          nickname:
            type: string
      ticketId:
        type: integer
        format: int64
      createdAt:
        type: string
      checkedAt:
        type: string
        description: '체크인한 시간, 체크인하지 않았으면 null'
      cancelledAt:
        type: string
        description: '파트너 페이지에서만 옴, 유저의 경우 취소한 예약은 오지 않습니다.'
  PaymentParams:
    type: object
    properties:
      cardNumber:
        type: string
        example: 1111-2222-3333-4444
      expiry:
        type: string
        example: 2018-03
        description: 카드 유효기간
      birth:
        type: string
        example: '920723'
        description: 카드 소유자 생년월일 (주민번호 앞 6자리)
      password:
        type: string
        description: 카드 비밀번호 앞 두자리
        example: '12'
      skipTrial:
        type: boolean
        description: true일 경우 무료체험 가능 여부를 검사하지 않고 바로 결제합니다.