openapi.yaml

openapi: 3.0.3
info:
  title: traPhoto(仮) API
  description: 画像とアルバムを管理するためのAPI
  version: 1.0.0
  contact:
    name: traP-jp
    url: https://github.com/traP-jp/1m25_10

servers:
  - url: http://localhost:3001
    description: 開発サーバー（モック）
  - url: https://api.your-domain.com
    description: 本番サーバー

paths:
  /images:
    get:
      summary: 全ての画像を取得
      description: 全ての画像のUUID配列を返します
      operationId: getImages
      tags:
        - Images
      responses:
        '200':
          description: 成功レスポンス
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  format: uuid
              example:
                - "0198cffa-4228-7afe-ac39-e0c88a0f0b81"
                - "01987e0e-bd1d-711f-ad98-1b37e53a6cd3"
        '500':
          $ref: '#/components/responses/ServerError'

  /api/auth/request:
    get:
      summary: traQ OAuth リクエスト
      description: ブラウザをtraQの認可画面へリダイレクトします（サーバー側でstate/code_verifierを一時Cookieに保存）
      operationId: authRequest
      tags:
        - Auth
      parameters:
        - name: callback
          in: query
          required: false
          description: '認証後に戻る相対パス（例: "/account"）'
          schema:
            type: string
      responses:
        '302':
          description: 認可サーバーへリダイレクト
          headers:
            Location:
              description: traQ 認可エンドポイント
              schema:
                type: string
        '500':
          $ref: '#/components/responses/ServerError'

  /api/auth/callback:
    get:
      summary: traQ OAuth コールバック
      description: 認可コードをアクセストークンに交換し、クッキーへ保存後にフロントへリダイレクト
      operationId: authCallback
      tags:
        - Auth
      parameters:
        - name: code
          in: query
          required: true
          schema:
            type: string
        - name: state
          in: query
          required: true
          schema:
            type: string
      responses:
        '302':
          description: フロントエンドへリダイレクト（Set-Cookie でセッション用トークンを設定）
          headers:
            Location:
              description: 'リダイレクト先（callback 指定があればそれ、なければ"/"）'
              schema:
                type: string
        '400':
          description: code/state が不正
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: 認可サーバーとのトークン交換に失敗
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/auth/me:
    get:
      summary: ログイン中ユーザー情報
      description: traQ の /users/me を代理取得した最小限のプロフィールを返します。
      operationId: authMe
      tags:
        - Auth
      security:
        - CookieAuth: []
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Me'
        '401':
          description: 未認証
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/auth/logout:
    post:
      summary: ログアウト
      description: セッションCookieを破棄します。
      operationId: authLogout
      tags:
        - Auth
      responses:
        '204':
          description: 成功（内容なし）
        '500':
          $ref: '#/components/responses/ServerError'

  /api/v1/traq/files/{uuid}:
    get:
      summary: traQファイル本体取得
      description: traQ APIを経由してファイル本体を取得し、クライアントにプロキシします。ユーザーのtraQ認証トークンを使用してアクセス権限を検証します。
      operationId: getTraqFile
      tags:
        - traQ Files
      security:
        - CookieAuth: []
      parameters:
        - name: uuid
          in: path
          required: true
          description: traQファイルのUUID
          schema:
            type: string
            format: uuid
          example: "550e8400-e29b-41d4-a716-446655440001"
      responses:
        '200':
          description: ファイル本体
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
            image/gif:
              schema:
                type: string
                format: binary
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          description: 未認証
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: アクセス権限なし
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ファイルが見つかりません
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/ServerError'

  /api/v1/traq/files/{uuid}/thumbnail:
    get:
      summary: traQファイルサムネイル取得
      description: traQ APIを経由してファイルのサムネイル画像を取得し、クライアントにプロキシします。ユーザーのtraQ認証トークンを使用してアクセス権限を検証します。
      operationId: getTraqFileThumbnail
      tags:
        - traQ Files
      security:
        - CookieAuth: []
      parameters:
        - name: uuid
          in: path
          required: true
          description: traQファイルのUUID
          schema:
            type: string
            format: uuid
          example: "550e8400-e29b-41d4-a716-446655440001"
      responses:
        '200':
          description: サムネイル画像
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
            image/gif:
              schema:
                type: string
                format: binary
        '401':
          description: 未認証
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: アクセス権限なし
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ファイルまたはサムネイルが見つかりません
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/ServerError'

  /api/v1/images/{id}:
    get:
      summary: ファイルUUIDから投稿詳細を取得
      description: '指定されたファイル/画像UUIDに対応するURL (https://q.trap.jp/files/{id}) を語句検索し、古い順で最も古い1件の投稿（作成者、本文、スタンプ等を含む）を返します。返却はtraQメッセージ検索のヒットオブジェクトをそのまま返します。'
      operationId: getLatestMessageByImageId
      tags:
        - Images
      security:
        - CookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: 画像のUUID
          schema:
            type: string
            format: uuid
          example: "550e8400-e29b-41d4-a716-446655440001"
      responses:
        '200':
          description: 最も古いヒット1件
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'

  # /images/{id}:
  #   get:
  #     summary: IDで画像詳細を取得
  #     description: 特定の画像の作成者と投稿データを含む詳細情報を返します
  #     operationId: getImageDetail
  #     tags:
  #       - Images
  #     parameters:
  #       - name: id
  #         in: path
  #         required: true
  #         description: 画像のUUID
  #         schema:
  #           type: string
  #           format: uuid
  #         example: "550e8400-e29b-41d4-a716-446655440001"
  #     responses:
  #       '200':
  #         description: 成功レスポンス
  #         content:
  #           application/json:
  #             schema:
  #               $ref: '#/components/schemas/ImageDetail'
  #       '404':
  #         $ref: '#/components/responses/NotFound'
  #       '500':
  #         $ref: '#/components/responses/ServerError'

  /albums:
    get:
      summary: 全てのアルバムを取得
      description: オプションのフィルタリングが可能なアルバムの配列を返します
      operationId: getAlbums
      tags:
        - Albums
      parameters:
        - name: creator_id
          in: query
          description: 作成者のUUIDでフィルタ
          schema:
            type: string
            format: uuid
        - name: before_date
          in: query
          description: この日付より前に作成されたアルバムでフィルタ
          schema:
            type: string
            format: date-time
        - name: after_date
          in: query
          description: この日付より後に作成されたアルバムでフィルタ
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          description: 返すアルバムの最大数（最大100）
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: offset
          in: query
          description: スキップするアルバム数
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: 成功レスポンス
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AlbumItem'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      summary: 新しいアルバムを作成
      description: 提供された情報で新しいアルバムを作成します。作成者は認証されたユーザーから決定されます。
      operationId: createAlbum
      tags:
        - Albums
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAlbumRequest'
      responses:
        '201':
          description: アルバムが正常に作成されました
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Album'
        '400':
          description: 無効なリクエスト
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 権限がありません
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/ServerError'

  /albums/{id}:
    get:
      summary: IDでアルバム詳細を取得
      description: 特定のアルバムの詳細情報を返します
      operationId: getAlbumDetail
      tags:
        - Albums
      parameters:
        - name: id
          in: path
          required: true
          description: アルバムのUUID
          schema:
            type: string
            format: uuid
          example: "550e8400-e29b-41d4-a716-446655440001"
      responses:
        '200':
          description: 成功レスポンス
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Album'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    put:
      summary: アルバムを更新（非推奨）
      description: 提供された情報で既存のアルバムを更新します。今後は PATCH を使用してください。
      operationId: updateAlbumUsingPut
      deprecated: true
      tags:
        - Albums
      parameters:
        - name: id
          in: path
          required: true
          description: アルバムのUUID
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAlbumRequest'
      responses:
        '200':
          description: アルバムが正常に更新されました
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Album'
        '400':
          description: 無効なリクエスト
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 権限がありません
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    patch:
      summary: アルバムを部分更新
      description: 提供されたフィールドのみを部分更新します
      operationId: updateAlbum
      tags:
        - Albums
      parameters:
        - name: id
          in: path
          required: true
          description: アルバムのUUID
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAlbumRequest'
      responses:
        '200':
          description: アルバムが正常に更新されました
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Album'
        '400':
          description: 無効なリクエスト
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 権限がありません
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    delete:
      summary: アルバムを削除
      description: 既存のアルバムを削除します
      operationId: deleteAlbum
      tags:
        - Albums
      parameters:
        - name: id
          in: path
          required: true
          description: アルバムのUUID
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: アルバムが正常に削除されました
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 権限がありません
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'

components:
  schemas:
    Me:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          description: traQ のユーザーID
          example: "01234567-89ab-cdef-0123-456789abcdef"
        name:
          type: string
          description: traQ のユーザー名
          example: "username"
        displayName:
          type: string
          description: 表示名（未設定の場合は省略される）
          example: "ユーザーネーム"
    Post:
      type: object
      required:
        - id
        - content
      properties:
        id:
          type: string
          format: uuid
          description: 投稿の一意識別子
          example: "0198cffa-42a2-7afe-b478-c11c146a2332"
        content:
          type: string
          description: 投稿の内容
          example: "かわいい"
    Image:
      type: object
      required:
        - id
        - creator
        - post
      properties:
        id:
          type: string
          format: uuid
          description: 画像の一意識別子
          example: "0198cffa-4228-7afe-ac39-e0c88a0f0b81"
        creator:
          type: string
          format: uuid
          description: 画像作成者の一意識別子
          example: "019619d0-e53a-7be9-add3-5096a746a93d"
        post:
          $ref: '#/components/schemas/Post'

    ImageDetail:
      type: object
      required:
        - id
        - creator
        - post
      properties:
        id:
          type: string
          format: uuid
          description: 画像の一意識別子
          example: "550e8400-e29b-41d4-a716-446655440001"
        creator:
          type: string
          format: uuid
          description: 画像作成者の一意識別子
          example: "019619d0-e53a-7be9-add3-5096a746a93d"
        post:
          $ref: '#/components/schemas/Post'

    Album:
      type: object
      required:
        - id
        - title
        - description
        - creator
        - images
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          description: アルバムの一意識別子
          example: "550e8400-e29b-41d4-a716-446655440001"
        title:
          type: string
          description: アルバムのタイトル
          example: "夏の思い出"
        description:
          type: string
          description: アルバムの説明
          example: "2024年夏の写真集"
        creator:
          type: string
          format: uuid
          description: アルバム作成者のUUID
          example: "550e8400-e29b-41d4-a716-446655440002"
        images:
          type: array
          items:
            type: string
            format: uuid
          description: アルバム内の画像UUIDの配列
          example: 
            - "550e8400-e29b-41d4-a716-446655440003"
            - "550e8400-e29b-41d4-a716-446655440004"
        created_at:
          type: string
          format: date-time
          description: 作成タイムスタンプ
          example: "2024-07-01T00:00:00Z"
        updated_at:
          type: string
          format: date-time
          description: 最終更新タイムスタンプ
          example: "2024-08-15T10:30:00Z"

    AlbumItem:
      type: object
      required:
        - id
        - title
        - creator
      properties:
        id:
          type: string
          format: uuid
          description: アルバムの一意識別子
          example: "550e8400-e29b-41d4-a716-446655440001"
        title:
          type: string
          description: アルバムのタイトル
          example: "夏の思い出"
        creator:
          type: string
          format: uuid
          description: アルバム作成者のUUID
          example: "550e8400-e29b-41d4-a716-446655440002"
        images:
          type: array
          items:
            type: string
            format: uuid
          description: アルバム内の画像UUIDの配列
          example: 
            - "550e8400-e29b-41d4-a716-446655440003"
            - "550e8400-e29b-41d4-a716-446655440004"
        created_at:
          type: string
          format: date-time
          description: 作成タイムスタンプ
          example: "2024-07-01T00:00:00Z"
        updated_at:
          type: string
          format: date-time
          description: 最終更新タイムスタンプ
          example: "2024-08-15T10:30:00Z"

    CreateAlbumRequest:
      type: object
      required:
        - title
        - description
      properties:
        title:
          type: string
          description: アルバムのタイトル
          example: "夏の思い出"
        description:
          type: string
          description: アルバムの説明
          example: "2024年夏の写真集"
        images:
          type: array
          items:
            type: string
            format: uuid
          description: アルバムに含める画像UUIDの配列
          example: 
            - "550e8400-e29b-41d4-a716-446655440003"
            - "550e8400-e29b-41d4-a716-446655440004"

    UpdateAlbumRequest:
      type: object
      properties:
        title:
          type: string
          description: アルバムのタイトル
          example: "夏の思い出 - 更新版"
        description:
          type: string
          description: アルバムの説明
          example: "2024年夏の写真集 - 追加写真あり"
        images:
          type: array
          items:
            type: string
            format: uuid
          description: アルバムに含める画像UUIDの配列
          example: 
            - "550e8400-e29b-41d4-a716-446655440003"
            - "550e8400-e29b-41d4-a716-446655440004"

    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: エラーメッセージ
          example: "Resource not found"
        message:
          type: string
          description: 追加のエラー詳細
          example: "The requested resource could not be found"

  responses:
    NotFound:
      description: 指定されたリソースが見つかりませんでした
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    
    ServerError:
      description: 内部サーバーエラー
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    
    Unauthorized:
      description: 認証に失敗しました。認証情報が提供されていないか無効です。
      headers:
        WWW-Authenticate:
          description: 'クライアントに通知する認証方式とオプションのエラー情報（例: Bearer realm="api", error="invalid_token"）'
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  securitySchemes:
    CookieAuth:
      type: apiKey
      in: cookie
      name: traq-auth-token
      description: traQ OAuth 交換後にサーバーがセットするアクセストークン Cookie

tags:
  - name: Images
    description: 画像に関する操作
  - name: Albums
    description: アルバムに関する操作
  - name: Auth
    description: 認証に関する操作
  - name: traQ Files
    description: traQファイルプロキシに関する操作