openapi: '3.0.3'
info:
  title: zzyxyz_api
  description: API服务
  version: '1.0'
servers:
  - url: http://localhost:8080/api
    description: 开发环境
  - url: https://api.zzyxyz.com/api
    description: 生产环境
tags:
  - name: folder
    description: 文件夹相关操作
  - name: data
    description: 书签相关操作
security:
  - ApiKeyAuth: []

paths:
  /bookmarks/v1/folder:
    post:
      summary: 创建文件夹
      description: 创建一个存储书签或者文件夹的文件夹
      operationId: createFolder
      tags: [folder]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FolderRequest'
      responses:
        '201':
          description: 创建成功的文件夹
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/ServerInternalError'

  /bookmarks/v1/folder/{id}:
    get:
      summary: 获取文件夹基础信息
      description: 获取文件夹基础信息不包含内容,只有元数据
      operationId: getFolderInfo
      tags: [folder]
      parameters:
        - name: id
          in: path
          required: true
          example: 1
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 文件夹详情
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderResponse'
        '404':
          description: 文件夹不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    
    put:
      summary: 更新文件夹
      description: 修改文件夹的元数据(包括修改名称和移动文件夹)
      operationId: updateFolder
      tags: [folder]
      parameters:
        - name: id
          in: path
          example: 1
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FolderRequest'
      responses:
        '200':
          description: 更新后的文件夹
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 文件夹不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/ServerInternalError'

    delete:
      summary: 删除文件夹
      description: 删除文件夹(文件夹不能有内容)
      operationId: deleteFolder
      tags: [folder]
      parameters:
        - name: id
          in: path
          example: 1
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '204':
          description: 删除成功
        '400':
          description: 文件夹不为空，无法删除
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 文件夹不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/ServerInternalError'

  /bookmarks/v1/folder/{id}/content:
    get:
      summary: 获取文件夹的内容
      description: 只获取当前文件夹的内容,不会递归搜索
      operationId: getFolderContent
      tags: [folder]
      parameters:
        - name: id
          in: path
          example: 1
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 文件夹子节点列表
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderContentResponse'
        '404':
          description: 文件夹不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: 删除文件夹的内容
      description: 删除文件夹的内容(危险操作)
      operationId: deleteFolderContent
      tags: [folder]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: mode
          in: query
          description: 删除模式
          required: false
          schema:
            type: string
            enum: [onlyContent, onlyEmptyFolder, onlyFolder, all]
      responses:
        '200':
          description: 删除成功
        '500':
          $ref: '#/components/responses/ServerInternalError'

  /bookmarks/v1/data:
    post:
      summary: 创建书签
      description: 在文件夹下创建一个书签
      operationId: createBookmark
      tags: [data]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookmarkRequest'
      responses:
        '201':
          description: 创建成功的书签
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookmarkResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/ServerInternalError'

  /bookmarks/v1/data/{id}:
    get:
      summary: 获取书签详情
      description: 通过id获取书签内容
      operationId: getBookmark
      tags: [data]
      parameters:
        - name: id
          in: path
          example: 1
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 书签详情
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookmarkResponse'
        '404':
          description: 书签不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    
    put:
      summary: 更新书签
      description: 更新指定id的书签
      operationId: updateBookmark
      tags: [data]
      parameters:
        - name: id
          in: path
          example: 1
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookmarkRequest'
      responses:
        '200':
          description: 更新后的书签
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookmarkResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 书签不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/ServerInternalError'
    
    delete:
      summary: 删除书签
      description: 删除指定id的书签
      operationId: deleteBookmark
      tags: [data]
      parameters:
        - name: id
          in: path
          example: 1
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '204':
          description: 删除成功
        '404':
          description: 书签不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/ServerInternalError'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
  responses:
    ServerInternalError:
      description: 服务器内部错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: 未授权
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    FolderRequest:
      description: 文件夹请求结构体
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: 文件夹名称
          example: 测试名称
        parent_path_id:
          type: integer
          format: int64
          description: 父文件夹ID 若为空则自动创建在用户根目录下
          example: 1
      required:
        - name

    BookmarkRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: 书签名称
          example: 测试名称
        link:
          type: string
          description: 书签链接
          example: /swagger/index.html
        detail:
          type: string
          description: 书签详情链接
        description:
          type: string
          description: 书签描述
        parent_path_id:
          type: integer
          format: int64
          description: 父文件夹ID 若为空则自动创建在用户根目录下
          example: 1
      required:
        - name

    FolderResponse:
      type: object
      description: 文件夹响应结构体
      properties:
        id:
          type: integer
          format: int64
          description: 文件夹ID
        name:
          type: string
          description: 文件夹名称
        parent_path_id:
          type: integer
          format: int64
          description: 父文件夹ID
        created_at:
          type: string
          format: date-time
          description: 创建时间
        updated_at:
          type: string
          format: date-time
          description: 更新时间
        sub_folder_count:
          type: integer
          description: 子文件夹数量
        bookmark_count:
          type: integer
          description: 书签数量
      required:
        - id
        - name
        - parent_path_id
        - created_at
        - updated_at
        - sub_folder_count
        - bookmark_count

    BookmarkResponse:
      type: object
      description: 书签相应结构体
      properties:
        id:
          type: integer
          format: int64
          description: 书签ID
        name:
          type: string
          description: 书签名称
        link:
          type: string
          description: 书签链接
        detail:
          type: string
          description: 书签详情链接
        description:
          type: string
          description: 书签描述
        parent_path_id:
          type: integer
          format: int64
          description: 父文件夹ID
        created_at:
          type: string
          format: date-time
          description: 创建时间
        updated_at:
          type: string
          format: date-time
          description: 更新时间
      required:
        - id
        - name
        - parent_path_id
        - created_at
        - updated_at

    FolderContentResponse:
      type: object
      properties:
        sub_folders:
          type: array
          items:
            $ref: '#/components/schemas/FolderBriefResponse'
          description: 子文件夹列表
        bookmarks:
          type: array
          items:
            $ref: '#/components/schemas/BookmarkBriefResponse'
          description: 书签列表
      required:
        - sub_folders
        - bookmarks

    FolderBriefResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: 文件夹ID
        name:
          type: string
          description: 文件夹名称
      required:
        - id
        - name

    BookmarkBriefResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: 书签ID
        name:
          type: string
          description: 书签名称
      required:
        - id
        - name

    Error:
      type: object
      description: 错误信息
      properties:
        errtype:
          type: string
          example: "ParameterError"
          description: 错误类型
        message:
          example: "传递的第一个参数错误"
          type: string
          description: 错误信息
      required:
        - errtype
        - message