openapi.yaml

openapi: 3.0.3
info:
  title: QuickWiki API
  version: 1.0.0
  description: API for QuickWiki
tags:
  - name: ping
    description: 疎通確認
  - name: lecture
    description: 講習会情報
  - name: wiki
    description: sodanと備忘録
  - name: sodan
    description: 匿名sodan
  - name: user
    description: ユーザー関連
  - name: other
    description: その他 TraQとの通信など
paths:
  /ping:
    get:
      tags:
        - ping
      summary: 疎通確認
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ping'
  /lecture:
    post:
      tags:
        - lecture
      summary: 新しい講習会情報の作成
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/lectureWithoutId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lecture'
  /lecture/{lectureId}:
    get:
      tags:
        - lecture
      summary: 1つの講習会情報の取得
      parameters:
        - name: lectureId
          in: path
          required: true
          schema:
            type: string
          description: 講習会ID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lecture'
        '400':
          description: 講習会IDが整数でないと思われる
        '404':
          description: 講習会IDに対応する講習会が見つからない
  /lecture/byFolder/id/{folderId}:
    get:
      tags:
        - lecture
      summary: フォルダに対応する講習会のリストを取得
      parameters:
        - name: folderId
          in: path
          required: true
          schema:
            type: integer
          description: フォルダID
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lectureList'
        '400':
          description: フォルダIDが整数でないと思われる
        '404':
          description: フォルダIDに対応する講習会が見つからない
  /lecture/byFolder/path:
    get:
      tags:
        - lecture
      summary: フォルダに対応する講習会のリストを取得
      parameters:
        - name: folderpath
          in: query
          required: true
          schema:
            type: string
            example: School-ComputerScience-Python
          description: フォルダパス ハイフン区切り
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lectureList'
        '404':
          description: フォルダパスに対応する講習会が見つからない
  /lecture/folder/{folderId}:
    get:
      tags:
        - lecture
      summary: 子フォルダのリストの取得
      parameters:
        - name: folderId
          in: path
          required: true
          schema:
            type: string
          description: フォルダID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/folderList'
        '400':
          description: フォルダIDが整数でないと思われる
  /wiki/search:
    post:
      tags:
        - wiki
      summary: sodanと備忘録の検索
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/searchRequest'
      description: sortはcreatedAt_oldest, createdAt_newest
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wikiList'
  /wiki/tag:
    get:
      tags:
        - wiki
      summary: タグに対応するsodanと備忘録のリストを取得
      parameters:
        - name: tag
          in: query
          required: true
          schema:
            type: string
          description: タグ 複数あってもよい
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wikiList'
    post:
      tags:
        - wiki
      summary: wikiにタグを追加
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/wikiTag'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wikiTag'
    patch:
      tags:
        - wiki
      summary: wikiのタグを更新
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/wikiTagPatch'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wikiTag'
    delete:
      tags:
        - wiki
      summary: wikiのタグを削除
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/wikiTag'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wikiTag'
  /sodan:
    get:
      tags:
        - wiki
      summary: 特定のsodanを取得
      parameters:
        - name: wikiId
          in: query
          required: true
          schema:
            type: string
          description: wikiID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sodan'
        '400':
          description: wikiIDが整数でないと思われる
        '404':
          description: wikiIDに対応するsodanが見つからない or メッセージ or スタンプ or タグが見つからない
      description: answerMessagesには，回答に対してもう一度する質問も含まれる
  /memo:
    get:
      tags:
        - wiki
      summary: 備忘録の取得
      parameters:
        - name: wikiId
          in: query
          required: true
          schema:
            type: string
          description: wikiID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/memo'
    post:
      tags:
        - wiki
      summary: 備忘録の作成
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/newMemo'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/memo'
    patch:
      tags:
        - wiki
      summary: 備忘録の更新
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateMemo'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/memo'
    delete:
      tags:
        - wiki
      summary: 備忘録の削除
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                wikiId:
                  type: string
                  example: 123
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/memo'
  /anon-sodan:
    post:
      tags:
        - sodan
      summary: 匿名のsodanの作成
      description: Endpoint to create a new anonymous sodan.
      requestBody:
        description: JSON object containing the content of the sodan.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                  example: "This is example content."
      responses:
        '200':
          description: Successfully created sodan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sodan'
    patch:
      tags:
        - sodan
      summary: 匿名sodanの編集
      description: Endpoint to edit an existing anonymous sodan.
      parameters:
        - name: wikiId
          in: query
          required: true
          schema:
            type: string
          description: wikiID
      requestBody:
        description: JSON object containing the ID and new content of the sodan.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                  example: "This is edited content."
      responses:
        '200':
          description: Successfully edited sodan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sodan'
  /anon-sodan/replies:
    post:
      tags:
      - sodan
      summary: 匿名相談の回答に対する返信
      description: Endpoint to reply to an anonymous sodan.
      parameters:
        - name: wikiId
          in: query
          description: The ID of the sodan to which the reply is being made.
          required: true
          schema:
            type: integer
      requestBody:
        description: JSON object containing the reply content.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                  example: "This is a reply to the sodan."
      responses:
        '200':
          description: Successfully replied to the sodan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sodan'        
    
  /wiki/user:
    get:
      tags:
        - user
      summary: ユーザーの備忘録 & sodanの取得
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wikiList'
  /wiki/user/favorite:
    get:
      tags:
        - user
      summary: ユーザーのお気に入りの備忘録 & sodanの取得
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wikiList'
    post:
      tags:
        - user
      summary: ユーザーのお気に入りの備忘録 & sodanの追加
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                wikiId:
                  type: string
                  example: 123
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wikiAbstract'
    delete:
      tags:
        - user
      summary: ユーザーのお気に入りの備忘録 & sodanの削除
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                wikiId:
                  type: string
                  example: 123
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wikiAbstract'
  /tag:
    get:
      tags:
        - wiki
      summary: タグ一覧の取得
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tagList'
  /me:
    get:
      tags:
        - user
      summary: 自分の情報の取得
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user'
  /files/{fileID}:
    get:
      tags:
        - other
      summary: ファイルの取得(ダウンロード)
      parameters:
        - name: fileID
          in: path
          required: true
          schema:
            type: string
          description: ファイルID
      responses:
        '200':
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /stamps/{stampID}:
    get:
      tags:
        - other
      summary: スタンプの取得(ダウンロード)
      parameters:
        - name: stampID
          in: path
          required: true
          schema:
            type: string
          description: スタンプID
      responses:
        '200':
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary


components:
  schemas:
    ping:
      type: object
      properties:
        message:
          type: string
          example: Pong
    lecture:
      type: object
      properties:
        id:
          type: integer
          example: 123
        title:
          type: string
          example: Introduction to Computer Science
        content:
          type: string
          example: 資料へのリンク(URL)のみ
        folderpath:
          type: string
          example: /School/ComputerScience
    lectureList:
      type: array
      items:
        $ref: '#/components/schemas/lecture'
    wikiList:
      type: array
      items:
        $ref: '#/components/schemas/wikiAbstract'
    wikiAbstract:
      type: object
      properties:
        id:
          type: integer
          example: 123
        type:
          type: string
          example: sodan
        title:
          type: string
          example: Introduction to Computer Science
        Abstract:
          type: string
          example: This is an introductory course to computer science
        createdAt:
          type: string
          example: 2021-01-01 00:00:00
        updatedAt:
          type: string
          example: 2021-01-01 00:00:00
        ownerTraqId:
          type: string
          example: kavos
        tags:
          type: array
          items:
            type: string
            example: ComputerScience
        favorites:
          type: integer
          example: 3
    folderList:
      type: array
      items:
        type: object
        properties:
          id:
            type: integer
            example: 123
          name:
            type: string
            example: ComputerScience
          isFolder:
            type: boolean
            example: true
    newMemo:
      type: object
      properties:
        title:
          type: string
          example: Introduction to Computer Science
        content:
          type: string
          example: This is an introductory course to computer science
        tags: 
          type: array
          items:
            type: string
            example: "hoadsoih"
    updateMemo:
      type: object
      properties:
        id:
          type: integer
          example: 123
        title:
          type: string
          example: Introduction to Computer Science
        content:
          type: string
          example: This is an introductory course to computer science
    searchRequest:
      type: object
      properties:
        query:
          type: string
          example: 検索キーワード
        tags:
          type: array
          items:
            type: string
          example: [ComputerScience, Python]
        resultCount:
          type: integer
          example: 10
        from:
          type: integer
          example: 0
        sort:
          type: string
          example: createdAt_oldest
    lectureWithoutId:
      type: object
      properties:
        title:
          type: string
          example: Introduction to Computer Science
        content:
          type: string
          example: マークダウン形式 資料へのリンク
        folderpath:
          type: string
          example: /School/ComputerScience
    sodan:
      type: object
      properties:
        id:
          type: integer
          example: 123
        title:
          type: string
          example: Introduction to Computer Science
        channelId:
          type: string
          example: abcd-efgh-ijkl
        tags:
          type: array
          items:
            type: string
            example: ComputerScience
        questionMessage:
          $ref: '#/components/schemas/message'
        answerMessages:
          type: array
          items:
            $ref: '#/components/schemas/message'
        favorites:
          type: integer
          example: 3
    message:
      type: object
      properties:
        userTraqId:
          type: string
          example: kavos
        content:
          type: string
          example: メッセージの中身
        createdAt:
          type: string
          example: 2021-01-01 00:00:00
        updatedAt:
          type: string
          example: 2021-01-01 00:00:00
        messageTraqId:
          type: string
          example: abcd-efgh-ijkl
        stamps:
          type: array
          items:
            type: object
            properties:
              stampId:
                type: string
                example: abcd-efgh-ijkl
              count:
                type: integer
                example: 3
        citations:
          type: array
          items:
            $ref: '#/components/schemas/messageForCitations'
    messageForCitations:
      type: object
      properties:
        userTraqId:
          type: string
          example: kavos
        content:
          type: string
          example: メッセージの中身
        createdAt:
          type: string
          example: 2021-01-01 00:00:00
        updatedAt:
          type: string
          example: 2021-01-01 00:00:00
    memo:
      type: object
      properties:
        id:
          type: integer
          example: 123
        title:
          type: string
          example: Introduction to Computer Science
        content:
          type: string
          example: This is an introductory course to computer science
        ownerTraqId:
          type: string
          example: kavos
        tags:
          type: array
          items:
            type: string
            example: ComputerScience
        createdAt:
          type: string
          example: 2021-01-01 00:00:00
        updatedAt:
          type: string
          example: 2021-01-01 00:00:00
        favorites:
          type: integer
          example: 3
    memoList:
      type: array
      items:
        $ref: '#/components/schemas/memo'
    user:
      type: object
      properties:
        traqId:
          type: string
          example: kavos
        name:
          type: string
          example: kavos
        iconUri:
          type: string
          example: あとで調べる
    tag:
      type: string
      example: ComputerScience
    tagList:
      type: array
      items:
        $ref: '#/components/schemas/tag'
    wikiTag:
      type: object
      properties:
        wikiId:
          type: string
          example: 123
        tag:
          type: string
          example: ComputerScience
    wikiTagPatch:
        type: object
        properties:
          wikiId:
            type: string
            example: 123
          tag:
            type: string
            example: ComputerScience
          newTag:
            type: string
            example: Python