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

paths:
  /bookmarks/v1/data/{id}:
    parameters:
      - name: id
        in: path
        example: 1
        required: true
        schema:
          type: integer
          format: int64

    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'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerInternalError'

    get:
      summary: 获取书签详情
      description: 通过id获取书签内容
      operationId: getBookmark
      tags: [data]
      responses:
        '200':
          description: 书签详情
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookmarkResponse'
        '404':
          description: 书签不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerInternalError'

    put:
      summary: 更新书签
      description: 更新指定id的书签
      operationId: updateBookmark
      tags: [data]
      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'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerInternalError'

    delete:
      summary: 删除书签
      description: 删除指定id的书签
      operationId: deleteBookmark
      tags: [data]
      responses:
        '204':
          description: 删除成功
        '404':
          description: 书签不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerInternalError'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-BookMark-Token
  responses:
    ServerInternalError:
      description: 服务器内部错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: 未授权
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: 无权限
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    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: 书签描述
      required:
        - name

    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: 书签描述
        created_at:
          type: string
          format: date-time
          description: 创建时间
        updated_at:
          type: string
          format: date-time
          description: 更新时间
      required:
        - id
        - name
        - created_at
        - updated_at

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