BingPaper/docs/swagger.yaml

basePath: /api/v1
definitions:
  config.APIConfig:
    properties:
      enableMktFallback:
        description: 当请求的地区不存在时，是否回退到默认地区
        type: boolean
      enableOnDemandFetch:
        description: 是否启用按需抓取
        type: boolean
      mode:
        description: local | redirect
        type: string
    type: object
  config.AdminConfig:
    properties:
      passwordBcrypt:
        type: string
    type: object
  config.Config:
    properties:
      admin:
        $ref: '#/definitions/config.AdminConfig'
      api:
        $ref: '#/definitions/config.APIConfig'
      cron:
        $ref: '#/definitions/config.CronConfig'
      db:
        $ref: '#/definitions/config.DBConfig'
      feature:
        $ref: '#/definitions/config.FeatureConfig'
      fetcher:
        $ref: '#/definitions/config.FetcherConfig'
      log:
        $ref: '#/definitions/config.LogConfig'
      retention:
        $ref: '#/definitions/config.RetentionConfig'
      server:
        $ref: '#/definitions/config.ServerConfig'
      storage:
        $ref: '#/definitions/config.StorageConfig'
      token:
        $ref: '#/definitions/config.TokenConfig'
      web:
        $ref: '#/definitions/config.WebConfig'
    type: object
  config.CronConfig:
    properties:
      dailySpec:
        type: string
      enabled:
        type: boolean
    type: object
  config.DBConfig:
    properties:
      dsn:
        type: string
      type:
        description: sqlite/mysql/postgres
        type: string
    type: object
  config.FeatureConfig:
    properties:
      writeDailyFiles:
        type: boolean
    type: object
  config.FetcherConfig:
    properties:
      regions:
        items:
          type: string
        type: array
    type: object
  config.LocalConfig:
    properties:
      root:
        type: string
    type: object
  config.LogConfig:
    properties:
      compress:
        description: 是否压缩旧日志文件
        type: boolean
      dbfilename:
        description: 数据库日志文件名
        type: string
      dblogLevel:
        description: '数据库日志级别: debug, info, warn, error'
        type: string
      filename:
        description: 业务日志文件名
        type: string
      level:
        type: string
      logConsole:
        description: 是否同时输出到控制台
        type: boolean
      maxAge:
        description: 保留旧日志文件最大天数
        type: integer
      maxBackups:
        description: 保留旧日志文件最大个数
        type: integer
      maxSize:
        description: 每个日志文件最大大小 (MB)
        type: integer
      showDBLog:
        description: 是否在控制台显示数据库日志
        type: boolean
    type: object
  config.RetentionConfig:
    properties:
      days:
        type: integer
    type: object
  config.S3Config:
    properties:
      accessKey:
        type: string
      bucket:
        type: string
      endpoint:
        type: string
      forcePathStyle:
        type: boolean
      publicURLPrefix:
        type: string
      region:
        type: string
      secretKey:
        type: string
    type: object
  config.ServerConfig:
    properties:
      baseURL:
        type: string
      port:
        type: integer
    type: object
  config.StorageConfig:
    properties:
      local:
        $ref: '#/definitions/config.LocalConfig'
      s3:
        $ref: '#/definitions/config.S3Config'
      type:
        description: local/s3/webdav
        type: string
      webDAV:
        $ref: '#/definitions/config.WebDAVConfig'
    type: object
  config.TokenConfig:
    properties:
      defaultTTL:
        type: string
    type: object
  config.WebConfig:
    properties:
      path:
        type: string
    type: object
  config.WebDAVConfig:
    properties:
      password:
        type: string
      publicURLPrefix:
        type: string
      url:
        type: string
      username:
        type: string
    type: object
  handlers.ChangePasswordRequest:
    properties:
      new_password:
        type: string
      old_password:
        type: string
    required:
    - new_password
    - old_password
    type: object
  handlers.CreateTokenRequest:
    properties:
      expires_at:
        description: optional
        type: string
      expires_in:
        description: optional, e.g. 168h
        type: string
      name:
        type: string
    required:
    - name
    type: object
  handlers.ImageMetaResp:
    properties:
      copyright:
        type: string
      copyrightlink:
        type: string
      date:
        type: string
      fullstartdate:
        type: string
      hsh:
        type: string
      mkt:
        type: string
      quiz:
        type: string
      startdate:
        type: string
      title:
        type: string
      variants:
        items:
          $ref: '#/definitions/handlers.ImageVariantResp'
        type: array
    type: object
  handlers.ImageVariantResp:
    properties:
      format:
        type: string
      size:
        type: integer
      storage_key:
        type: string
      url:
        type: string
      variant:
        type: string
    type: object
  handlers.LoginRequest:
    properties:
      password:
        type: string
    required:
    - password
    type: object
  handlers.ManualFetchRequest:
    properties:
      "n":
        type: integer
    type: object
  handlers.UpdateTokenRequest:
    properties:
      disabled:
        type: boolean
    type: object
  model.Token:
    properties:
      created_at:
        type: string
      disabled:
        type: boolean
      expires_at:
        type: string
      id:
        type: integer
      name:
        type: string
      token:
        type: string
      updated_at:
        type: string
    type: object
  util.Region:
    properties:
      label:
        type: string
      value:
        type: string
    type: object
host: localhost:8080
info:
  contact: {}
  description: 必应每日一图抓取、存储、管理与公共 API 服务。
  title: BingPaper API
  version: "1.0"
paths:
  /admin/cleanup:
    post:
      description: 立即启动旧图片清理任务
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties:
              type: string
            type: object
      security:
      - BearerAuth: []
      summary: 手动触发清理
      tags:
      - admin
  /admin/config:
    get:
      description: 获取服务的当前运行配置 (脱敏)
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/config.Config'
      security:
      - BearerAuth: []
      summary: 获取当前配置
      tags:
      - admin
    put:
      consumes:
      - application/json
      description: 在线更新服务配置并保存
      parameters:
      - description: 配置对象
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/config.Config'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/config.Config'
      security:
      - BearerAuth: []
      summary: 更新配置
      tags:
      - admin
  /admin/fetch:
    post:
      consumes:
      - application/json
      description: 立即启动抓取 Bing 任务
      parameters:
      - description: 抓取天数
        in: body
        name: request
        schema:
          $ref: '#/definitions/handlers.ManualFetchRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties:
              type: string
            type: object
      security:
      - BearerAuth: []
      summary: 手动触发抓取
      tags:
      - admin
  /admin/login:
    post:
      consumes:
      - application/json
      description: 使用密码登录并获取临时 Token
      parameters:
      - description: 登录请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handlers.LoginRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/model.Token'
        "401":
          description: Unauthorized
          schema:
            additionalProperties:
              type: string
            type: object
      summary: 管理员登录
      tags:
      - admin
  /admin/password:
    post:
      consumes:
      - application/json
      description: 验证旧密码并设置新密码，自动更新配置文件
      parameters:
      - description: 修改密码请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handlers.ChangePasswordRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties:
              type: string
            type: object
        "400":
          description: Bad Request
          schema:
            additionalProperties:
              type: string
            type: object
        "401":
          description: Unauthorized
          schema:
            additionalProperties:
              type: string
            type: object
      security:
      - BearerAuth: []
      summary: 修改管理员密码
      tags:
      - admin
  /admin/tokens:
    get:
      description: 获取所有已创建的 API Token 列表
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/model.Token'
            type: array
      security:
      - BearerAuth: []
      summary: 获取 Token 列表
      tags:
      - admin
    post:
      consumes:
      - application/json
      description: 创建一个新的 API Token
      parameters:
      - description: 创建请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handlers.CreateTokenRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/model.Token'
      security:
      - BearerAuth: []
      summary: 创建 Token
      tags:
      - admin
  /admin/tokens/{id}:
    delete:
      description: 永久删除指定的 API Token
      parameters:
      - description: Token ID
        in: path
        name: id
        required: true
        type: integer
      responses:
        "200":
          description: OK
          schema:
            additionalProperties:
              type: string
            type: object
      security:
      - BearerAuth: []
      summary: 删除 Token
      tags:
      - admin
    patch:
      consumes:
      - application/json
      description: 启用或禁用指定的 API Token
      parameters:
      - description: Token ID
        in: path
        name: id
        required: true
        type: integer
      - description: 更新请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handlers.UpdateTokenRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties:
              type: string
            type: object
      security:
      - BearerAuth: []
      summary: 更新 Token 状态
      tags:
      - admin
  /image/date/{date}:
    get:
      description: 根据日期返回图片流或重定向 (yyyy-mm-dd)
      parameters:
      - description: 日期 (yyyy-mm-dd)
        in: path
        name: date
        required: true
        type: string
      - description: 地区编码 (如 zh-CN, en-US)
        in: query
        name: mkt
        type: string
      - default: UHD
        description: 分辨率
        in: query
        name: variant
        type: string
      - default: jpg
        description: 格式
        in: query
        name: format
        type: string
      produces:
      - image/jpeg
      responses:
        "200":
          description: OK
          schema:
            type: file
        "202":
          description: 按需抓取任务已启动
          schema:
            additionalProperties:
              type: string
            type: object
        "404":
          description: 图片未找到，响应体包含具体原因
          schema:
            additionalProperties:
              type: string
            type: object
      summary: 获取指定日期图片
      tags:
      - image
  /image/date/{date}/meta:
    get:
      description: 根据日期获取图片元数据 (yyyy-mm-dd)
      parameters:
      - description: 日期 (yyyy-mm-dd)
        in: path
        name: date
        required: true
        type: string
      - description: 地区编码 (如 zh-CN, en-US)
        in: query
        name: mkt
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handlers.ImageMetaResp'
        "202":
          description: 按需抓取任务已启动
          schema:
            additionalProperties:
              type: string
            type: object
        "404":
          description: 图片未找到，响应体包含具体原因
          schema:
            additionalProperties:
              type: string
            type: object
      summary: 获取指定日期图片元数据
      tags:
      - image
  /image/random:
    get:
      description: 随机返回一张已抓取的图片流或重定向
      parameters:
      - description: 地区编码 (如 zh-CN, en-US)
        in: query
        name: mkt
        type: string
      - default: UHD
        description: 分辨率
        in: query
        name: variant
        type: string
      - default: jpg
        description: 格式
        in: query
        name: format
        type: string
      produces:
      - image/jpeg
      responses:
        "200":
          description: OK
          schema:
            type: file
        "202":
          description: 按需抓取任务已启动
          schema:
            additionalProperties:
              type: string
            type: object
        "404":
          description: 图片未找到，响应体包含具体原因
          schema:
            additionalProperties:
              type: string
            type: object
      summary: 获取随机图片
      tags:
      - image
  /image/random/meta:
    get:
      description: 随机获取一张已抓取图片的元数据
      parameters:
      - description: 地区编码 (如 zh-CN, en-US)
        in: query
        name: mkt
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handlers.ImageMetaResp'
        "202":
          description: 按需抓取任务已启动
          schema:
            additionalProperties:
              type: string
            type: object
        "404":
          description: 图片未找到，响应体包含具体原因
          schema:
            additionalProperties:
              type: string
            type: object
      summary: 获取随机图片元数据
      tags:
      - image
  /image/today:
    get:
      description: 根据参数返回今日必应图片流或重定向
      parameters:
      - description: 地区编码 (如 zh-CN, en-US)
        in: query
        name: mkt
        type: string
      - default: UHD
        description: 分辨率 (UHD, 1920x1080, 1366x768, 1280x720, 1024x768, 800x600, 800x480,
          640x480, 640x360, 480x360, 400x240, 320x240)
        in: query
        name: variant
        type: string
      - default: jpg
        description: 格式 (jpg)
        in: query
        name: format
        type: string
      produces:
      - image/jpeg
      responses:
        "200":
          description: OK
          schema:
            type: file
        "202":
          description: 按需抓取任务已启动
          schema:
            additionalProperties:
              type: string
            type: object
        "404":
          description: 图片未找到，响应体包含具体原因
          schema:
            additionalProperties:
              type: string
            type: object
      summary: 获取今日图片
      tags:
      - image
  /image/today/meta:
    get:
      description: 获取今日必应图片的标题、版权等元数据
      parameters:
      - description: 地区编码 (如 zh-CN, en-US)
        in: query
        name: mkt
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handlers.ImageMetaResp'
        "202":
          description: 按需抓取任务已启动
          schema:
            additionalProperties:
              type: string
            type: object
        "404":
          description: 图片未找到，响应体包含具体原因
          schema:
            additionalProperties:
              type: string
            type: object
      summary: 获取今日图片元数据
      tags:
      - image
  /images:
    get:
      description: '分页获取已抓取的图片元数据列表。支持分页(page, page_size)、限制数量(limit)和按月份过滤(month,
        格式: YYYY-MM)。'
      parameters:
      - default: 30
        description: 限制数量 (如果不使用分页)
        in: query
        name: limit
        type: integer
      - description: 页码 (从1开始)
        in: query
        name: page
        type: integer
      - description: 每页数量
        in: query
        name: page_size
        type: integer
      - description: '按月份过滤 (格式: YYYY-MM)'
        in: query
        name: month
        type: string
      - description: 地区编码 (如 zh-CN, en-US)
        in: query
        name: mkt
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/handlers.ImageMetaResp'
            type: array
      summary: 获取图片列表
      tags:
      - image
  /images/global/today:
    get:
      description: 获取配置文件中所有已开启地区的今日必应图片元数据（缩略图）
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/handlers.ImageMetaResp'
            type: array
      summary: 获取所有地区的今日图片列表
      tags:
      - image
  /regions:
    get:
      description: 返回系统支持的所有必应地区编码及标签。如果配置中指定了抓取地区，这些地区将排在列表最前面（置顶）。
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/util.Region'
            type: array
      summary: 获取支持的地区列表
      tags:
      - image
securityDefinitions:
  BearerAuth:
    in: header
    name: Authorization
    type: apiKey
swagger: "2.0"