openapi: 3.0.0
info:
  title: Bangumi API
  description: TODO
  # TODO: 版本不确定
  version: 1.0.0
servers:
  - url: https://api.bgm.tv
paths:
  /user/{username}:
    get:
      tags:
        - 用户
      summary: 用户信息
      parameters:
        - $ref: '#/components/parameters/username'
      responses:
        200:
          description: 返回用户基础信息
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /user/{username}/collection:
    get:
      tags:
        - 用户
      summary: 用户收藏
      parameters:
        - $ref: '#/components/parameters/username'
        - name: cat
          in: query
          description: 收藏类型
            <br> watching = 在看的动画与三次元条目
            <br> all_watching = 在看的动画三次元与书籍条目
          # TODO: 实际为必填，未填不返回数据
          required: false
          schema:
            type: string
            enum:
              - watching
              - all_watching
        - name: ids
          in: query
          description: 收藏条目 ID
            <br> 批量查询收藏状态，将条目 ID 以半角逗号分隔，如 1,2,4,6
          required: false
          schema:
            type: string
            example: 1,2,4,6
        # TODO: 实际该参数无效，返回永远为 SubjectSmall
        - name: responseGroup
          in: query
          description: 返回数据大小
            <br> 默认为 medium。small 时不返回条目详细信息
          required: false
          schema:
            type: string
            enum:
              - small
              - medium
            default: medium
      responses:
        200:
          description: 获取用户收藏列表，默认为在看
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      description: 番剧标题
                      type: string
                    ep_status:
                      description: 完成话数
                      type: integer
                    lasttouch:
                      description: 上次更新时间
                      type: integer
                    subject:
                      # TODO: 其中 summary 为空
                      $ref: '#/components/schemas/SubjectSmall'
  /user/{username}/collections/{subject_type}:
    get:
      tags:
        - 用户
      summary: 用户收藏概览
      parameters:
        - $ref: '#/components/parameters/username'
        - name: subject_type
          in: path
          description: 条目类型
            <br> book
            <br> anime
            <br> music
            <br> game
            <br> real
          required: true
          schema:
            $ref: '#/components/schemas/SubjectTypeName'
        - name: max_results
          in: query
          description: 显示条数
            <br> 最多 25
          schema:
            type: integer
            maximum: 25
      responses:
        200:
          description: 获取用户指定类型的收藏概览，固定返回最近更新的收藏，不支持翻页
            <br> TODO 数据结构未确定
            <br> [#3](https://github.com/bangumi/api/issues/3)
          content:
            application/json:
              schema:
                description: 收藏概览
                type: array
                items:
                  type: object
                  properties:
                    type:
                      $ref: '#/components/schemas/SubjectType'
                    name:
                      $ref: '#/components/schemas/SubjectTypeName'
                    name_cn:
                      description: 条目类型中文名
                      type: string
                      example: 动画
                    collects:
                      description: 收藏列表
                      type: array
                      items:
                        type: object
                        properties:
                          subject_id:
                            description: 条目 ID
                            type: integer
                          subject:
                            $ref: '#/components/schemas/SubjectSmall'
  /user/{username}/collections/status:
    get:
      tags:
        - 用户
      summary: 用户收藏统计
      parameters:
        - $ref: '#/components/parameters/username'
      responses:
        200:
          description: 获取用户所有收藏信息
          content:
            application/json:
              schema:
                description: 各个条目类型的收藏状态
                type: object
                properties:
                  1:
                    $ref: '#/components/schemas/CollectionsStatus'
                  2:
                    $ref: '#/components/schemas/CollectionsStatus'
                  3:
                    $ref: '#/components/schemas/CollectionsStatus'
                  4:
                    $ref: '#/components/schemas/CollectionsStatus'
                  6:
                    $ref: '#/components/schemas/CollectionsStatus'
  /user/{username}/progress:
    get:
      tags:
        - 用户
      summary: 用户收视进度
      parameters:
        - $ref: '#/components/parameters/username'
        - name: subject_id
          in: query
          description: 条目 ID
            <br> 获取指定条目收视进度
          schema:
            type: integer
      responses:
        200:
          description: TODO
          content:
            application/json:
              schema:
                description: 各个条目类型的收藏状态
  /subject/{subject_id}:
    get:
      tags:
        - 条目
      summary: 条目信息
      parameters:
        - $ref: '#/components/parameters/subject_id'
        - $ref: '#/components/parameters/responseGroup'
      responses:
        200:
          description: 根据 responseGroup 参数，返回以下三个模型
            <br> [SubjectSmall](#model-SubjectSmall)
            <br> [SubjectMedium](#model-SubjectMedium)
            <br> [SubjectLarge](#model-SubjectLarge)
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SubjectSmall'
                  - $ref: '#/components/schemas/SubjectMedium'
                  - $ref: '#/components/schemas/SubjectLarge'
  /subject/{subject_id}/ep:
    get:
      tags:
        - 条目
      summary: 章节数据
      parameters:
        - $ref: '#/components/parameters/subject_id'
      responses:
        200:
          description: 章节数据
          content:
            application/json:
              schema:
                allOf:
                  # TODO: summary、air_date、air_weekday 无数据；无 rating、rank 字段
                  - $ref: '#/components/schemas/SubjectSmall'
                  - type: object
                    properties:
                      eps:
                        description: 章节列表
                        type: array
                        items:
                          $ref: '#/components/schemas/Episode'
  /calendar:
    get:
      tags:
        - 条目
      summary: 每日放送
      responses:
        200:
          description: 每日放送
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    weekday:
                      type: object
                      properties:
                        en:
                          type: string
                          example: Mon
                        cn:
                          type: string
                          example: 星期一
                        ja:
                          type: string
                          example: 月耀日
                        id:
                          type: integer
                          example: 1
                    items:
                      type: array
                      items:
                        $ref: '#/components/schemas/SubjectSmall'
  /search/subject/{keywords}:
    get:
      tags:
        - 搜索
      summary: 条目搜索
      parameters:
        - name: keywords
          in: path
          description: 关键词
            <br> 需要 URL Encode
          required: true
          schema:
            type: string
        - name: type
          in: query
          description: 条目类型，参考 [SubjectType](#model-SubjectType)
          required: false
          schema:
            $ref: '#/components/schemas/SubjectType'
        - $ref: '#/components/parameters/responseGroup'
        - name: start
          in: query
          description: 开始条数
          required: false
          schema:
            type: integer
        - name: max_results
          in: query
          description: 每页条数
            <br> 最多 25
          required: false
          schema:
            type: integer
            maximum: 25
      responses:
        200:
          description: 搜索结果
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    description: 总条数
                    type: integer
                  list:
                    description: 结果列表
                    type: array
                    items:
                      $ref: '#/components/schemas/SubjectSmall'
  /ep/{id}/status/{status}:
    get:
      tags:
        - 进度
      summary: 获取收视进度
      parameters:
        - $ref: '#/components/parameters/ep_id'
        - $ref: '#/components/parameters/ep_status'
      responses:
        200:
          description: TODO
          content:
            application/json:
              schema:
                type: object
    post:
      tags:
        - 进度
      summary: 更新收视进度
      parameters:
        - $ref: '#/components/parameters/ep_id'
        - $ref: '#/components/parameters/ep_status'
        - name: ep_id
          in: query
          description: 使用 POST 批量更新
            <br> 将章节以半角逗号分隔，如 `3697,3698,3699`。请求时 URL 中的 ep_id 为最后一个章节 ID
          required: false
          schema:
            type: string
            example: 3697,3698,3699
      responses:
        200:
          description: TODO
          content:
            application/json:
              schema:
                type: object
  /subject/{subject_id}/update/watched_eps:
    post:
      tags:
        - 进度
      summary: 批量更新收视进度
      parameters:
        - $ref: '#/components/parameters/subject_id'
        - name: watched_eps
          in: query
          description: 如看到 123 话则 POST `123`
          # TODO: watched_eps 和 watched_vols 必填其一？
          required: true
          schema:
            type: string
            example: 123
        - name: watched_vols
          in: query
          description: 如看到第 3 卷则 POST `3`, 仅对书籍条目有效
          required: false
          schema:
            type: string
            example: 3
      responses:
        200:
          description: TODO
          content:
            application/json:
              schema:
                type: object
  /collection/{subject_id}:
    get:
      tags:
        - 收藏
      summary: 获取指定条目收藏信息
      parameters:
        - $ref: '#/components/parameters/subject_id'
      responses:
        200:
          description: TODO
          content:
            application/json:
              schema:
                type: object
  /collection/{subject_id}/create:
    post:
      tags:
        - 收藏
      summary: 添加收藏
      parameters:
        - $ref: '#/components/parameters/subject_id'
      responses:
        200:
          description: TODO
          content:
            application/json:
              schema:
                type: object
  /collection/{subject_id}/update:
    post:
      tags:
        - 收藏
      summary: 更新收藏
      parameters:
        - $ref: '#/components/parameters/subject_id'
        - name: status
          in: query
          description: 章节状态
          required: true
          schema:
            $ref: '#/components/schemas/EpStatus'
        - name: comment
          in: query
          description: 简评
          required: false
          schema:
            type: string
        - name: tags
          in: query
          description: 标签
            <br> 以半角空格分割
          required: false
          schema:
            type: string
        - name: rating
          in: query
          description: 评分
            <br> 1-10
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 10
            example: 7
        - name: privacy
          in: query
          description: 收藏隐私
            <br> 0 = 公开
            <br> 1 = 私密
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
            default: 0
      responses:
        200:
          description: TODO
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    CollectionsStatus:
      description: 各个类型的收藏数量
      type: array
      items:
        type: object
        properties:
          type:
            description: 收藏类型
            type: integer
            enum:
              - 1
              - 2
              - 3
              - 4
              - 5
            example: 5
          name:
            $ref: '#/components/schemas/CollectionStatus'
          name_cn:
            description: 收藏类型中文
            type: string
            example: 抛弃
          count:
            description: 数量
            type: integer
            example: 1
    CollectionStatus:
      description: 收藏状态
        <br> wish = 想做
        <br> collect = 做过
        <br> do = 在做
        <br> on_hold = 搁置
        <br> dropped = 抛弃
      type: string
      enum:
        - wish
        - collect
        - do
        - on_hold
        - dropped
      example: dropped
    EpStatus:
      description: 章节状态
        <br> watched = 看过
        <br> queue = 想看
        <br> drop = 抛弃
        <br> remove = 撤销
      type: string
      enum:
        - watched
        - queue
        - drop
        - remove
    ResponseGroup:
      description: 返回数据大小
      type: string
      enum:
        - small
        - medium
        - large
      default: small
    MonoBase:
      description: 人物（基础模型）
      type: object
      properties:
        id:
          description: 人物 ID
          type: integer
        url:
          description: 人物地址
          type: string
        name:
          description: 姓名
          type: string
        images:
          description: 肖像
          type: object
          properties:
            large:
              type: string
              example: http://lain.bgm.tv/pic/crt/l/ce/65/32_crt_XMJOj.jpg
            medium:
              type: string
              example: http://lain.bgm.tv/pic/crt/m/ce/65/32_crt_XMJOj.jpg
            small:
              type: string
              example: http://lain.bgm.tv/pic/crt/s/ce/65/32_crt_XMJOj.jpg
            grid:
              type: string
              example: http://lain.bgm.tv/pic/crt/g/ce/65/32_crt_XMJOj.jpg
    Mono:
      description: 人物
      allOf:
        - $ref: '#/components/schemas/MonoBase'
        - type: object
          properties:
            name_cn:
              description: 简体中文名
              type: string
            comment:
              description: 回复数量
              type: integer
            collects:
              description: 收藏人数
              type: integer
    MonoInfo:
      description: 人物信息（TODO 待完善）
      type: object
      properties:
        birth:
          description: 生日
          type: string
          example: 4月13日
        height:
          description: 身高
          type: string
          example: 152cm
        gender:
          description: 性别
          type: string
          example: 女
        alias:
          description: 别名（TODO 待完善，字段名为数字的情况）
          type: object
          properties:
            jp:
              description: 日文名
              type: string
            kana:
              description: 纯假名
              type: string
            nick:
              description: 昵称
              type: string
            romaji:
              description: 罗马字
              type: string
            zh:
              description: 第二中文名
              type: string
        source:
          description: 引用来源（TODO 待完善，可以是字符串类型）
          type: array
          items:
            type: string
            example: anidb.net
        name_cn:
          description: 简体中文名
          type: string
        cv:
          description: 声优
          type: string
    Person:
      description: 现实人物
      allOf:
        - $ref: '#/components/schemas/Mono'
        - type: object
          properties:
            info:
              $ref: '#/components/schemas/MonoInfo'
    Character:
      description: 虚拟角色
      allOf:
        - $ref: '#/components/schemas/Mono'
        - type: object
          properties:
            info:
              $ref: '#/components/schemas/MonoInfo'
            actors:
              description: 声优列表
              type: array
              items:
                $ref: '#/components/schemas/MonoBase'
    EpisodeType:
      description: 章节类型
        <br> 0 = 本篇
        <br> 1 = 特别篇
        <br> 2 = OP
        <br> 3 = ED
        <br> 4 = 预告/宣传/广告
        <br> 5 = MAD
        <br> 6 = 其他
        <br> TODO 待确定
      type: integer
      enum:
        - 0
        - 1
        - 2
        - 3
        - 4
        - 5
        - 6
      example: 0
    Episode:
      description: 章节信息
      type: object
      properties:
        id:
          description: 章节 ID
          type: integer
          example: 1027
        url:
          description: 章节地址
          type: string
          example: http://bgm.tv/ep/1027
        type:
          $ref: '#/components/schemas/EpisodeType'
        sort:
          description: 集数
          type: integer
          example: 1
        name:
          description: 标题
          type: string
          example: ちぃ 目覚める
        name_cn:
          description: 简体中文标题
          type: string
          example: 叽，觉醒了
        duration:
          description: 时长
          type: string
          example: 24m
        airdate:
          description: 放送日期
          type: string
          example: '2002-04-03'
        comment:
          description: 回复数量
          type: integer
          example: 9
        desc:
          description: 简介
          type: string
        status:
          description: 放送状态
            <br> Air = 已放送
            <br> Today = 正在放送
            <br> NA = 未放送
            <br> TODO 待确定
          type: string
          enum:
            - Air
            - Today
            - NA
          example: Air
    Topic:
      description: 讨论版
      type: object
      properties:
        id:
          description: ID
          type: integer
        url:
          description: 地址
          type: string
        title:
          description: 标题
          type: string
        main_id:
          description: 所属对象（条目） ID
          type: integer
        timestamp:
          description: 发布时间
          type: integer
        lastpost:
          description: 最后回复时间
          type: integer
        replies:
          description: 回复数
          type: integer
        user:
          $ref: '#/components/schemas/User'
    Blog:
      description: 日志
      type: object
      properties:
        id:
          description: ID
          type: integer
        url:
          description: 地址
          type: string
        title:
          description: 标题
          type: string
        summary:
          description: 概览
          type: string
        image:
          description: 图片（TODO 非数组？第一张？）
          type: string
        replies:
          description: 回复数
          type: integer
        timestamp:
          description: 发布时间
          type: integer
          example: 1357144903
        dateline:
          description: 发布时间
          type: string
          example: 2013-1-2 16:41
        user:
          $ref: '#/components/schemas/User'
    SubjectType:
      description: 条目类型
        <br> 1 = book
        <br> 2 = anime
        <br> 3 = music
        <br> 4 = game
        <br> 6 = real
      type: integer
      enum:
        - 1
        - 2
        - 3
        - 4
        - 6
      example: 2
    SubjectTypeName:
      description: 条目类型名称
        <br> book
        <br> anime
        <br> music
        <br> game
        <br> real
      type: string
      enum:
        - book
        - anime
        - music
        - game
        - real
      example: anime
    SubjectSmall:
      type: object
      properties:
        id:
          description: 条目 ID
          type: integer
          example: 12
        url:
          description: 条目地址
          type: string
          example: http://bgm.tv/subject/12
        type:
          $ref: '#/components/schemas/SubjectType'
        name:
          description: 条目名称
          type: string
          example: ちょびっツ
        name_cn:
          description: 条目中文名称
          type: string
          example: 人形电脑天使心
        summary:
          description: 剧情简介
          type: string
          example: 在不久的将来,电子技术飞速发展,电脑成为人们生活中不可缺少的一部分.主角的名字是本须和秀树,是个19岁的少年,由于考试失败,来到东京上补习班,过着贫穷潦倒的生活……\r\n到达东京的第一天,他很幸运的在垃圾堆捡到一个人型电脑,一直以来秀树都非常渴望拥有个人电脑.当他抱着她带返公寓后,却不知如何开机,在意想不到的地方找到开关并开启后,故事就此展开\r\n本须和秀树捡到了人型计算机〔唧〕。虽然不晓得她到底是不是〔Chobits〕，但她的身上似乎藏有极大的秘密。看到秀树为了钱而烦恼，唧出去找打工，没想到却找到了危险的工作！为了让秀树开心，唧开始到色情小屋打工。但她在遭到过度激烈的强迫要求之后失控。让周遭计算机因此而强制停摆。\r\n另一方面，秀树发现好友新保与补习班的清水老师有着不可告人的关系……
        eps:
          description: 话数
          type: integer
          example: 27
        air_date:
          description: 放送开始日期
          type: string
          example: '2002-04-02'
        air_weekday:
          description: 放送星期
          type: integer
          example: 2
        rating:
          description: 放送星期
          type: object
          properties:
            total:
              description: 总评分人数
              type: integer
              example: 2289
            count:
              description: 各分值评分人数
              type: object
              properties:
                1:
                  type: integer
                  example: 5
                2:
                  type: integer
                  example: 3
                3:
                  type: integer
                  example: 4
                4:
                  type: integer
                  example: 6
                5:
                  type: integer
                  example: 46
                6:
                  type: integer
                  example: 267
                7:
                  type: integer
                  example: 659
                8:
                  type: integer
                  example: 885
                9:
                  type: integer
                  example: 284
                10:
                  type: integer
                  example: 130
            score:
              description: 评分
              type: number
              example: 7.6
        rank:
          description: 排名
          type: integer
          example: 573
        images:
          description: 封面
          type: object
          properties:
            large:
              type: string
              example: http://lain.bgm.tv/pic/cover/l/c2/0a/12_24O6L.jpg
            common:
              type: string
              example: http://lain.bgm.tv/pic/cover/c/c2/0a/12_24O6L.jpg
            medium:
              type: string
              example: http://lain.bgm.tv/pic/cover/m/c2/0a/12_24O6L.jpg
            small:
              type: string
              example: http://lain.bgm.tv/pic/cover/s/c2/0a/12_24O6L.jpg
            grid:
              type: string
              example: http://lain.bgm.tv/pic/cover/g/c2/0a/12_24O6L.jpg
        collection:
          description: 收藏人数
          type: object
          properties:
            wish:
              description: 想做
              type: integer
              example: 608
            collect:
              description: 做过
              type: integer
              example: 3010
            doing:
              description: 在做
              type: integer
              example: 103
            on_hold:
              description: 搁置
              type: integer
              example: 284
            dropped:
              description: 抛弃
              type: integer
              example: 86
    SubjectMedium:
      allOf:
        - $ref: '#/components/schemas/SubjectSmall'
        - type: object
          properties:
            crt:
              description: 角色信息
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/Character'
                  - type: object
                    properties:
                      role_name:
                        description: 角色类型
                        type: string
                        example: 主角
            staff:
              description: 制作人员信息
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/Person'
                  - type: object
                    properties:
                      role_name:
                        description: 人物类型
                        type: string
                        example: 主角
                      jobs:
                        description: 职位
                        type: array
                        items:
                          type: string
    SubjectLarge:
      allOf:
        - $ref: '#/components/schemas/SubjectMedium'
        - type: object
          properties:
            eps:
              description: 章节列表
              type: array
              items:
                $ref: '#/components/schemas/Episode'
            topic:
              description: 讨论版
              type: array
              items:
                $ref: '#/components/schemas/Topic'
            blog:
              description: 评论日志
              type: array
              items:
                $ref: '#/components/schemas/Blog'
    User:
      description: 用户信息
      type: object
      properties:
        id:
          description: 用户 id
          type: integer
          example: 1
        url:
          description: 用户主页地址
          type: string
          example: http://bgm.tv/user/sai
        username:
          description: 用户名
          type: string
          example: sai
        nickname:
          description: 昵称
          type: string
          example: Sai
        avatar:
          description: 头像地址
          type: object
          properties:
            large:
              type: string
              example: http://lain.bgm.tv/pic/user/l/000/00/00/1.jpg?r=1391790456
            medium:
              type: string
              example: http://lain.bgm.tv/pic/user/m/000/00/00/1.jpg?r=1391790456
            small:
              type: string
              example: http://lain.bgm.tv/pic/user/s/000/00/00/1.jpg?r=1391790456
        sign:
          description: 签名
          type: string
          example: Awesome!
  parameters:
    username:
      name: username
      in: path
      description: 用户名
        <br> 也可使用 UID
      required: true
      schema:
        type: string
        example: sai
    subject_id:
      name: subject_id
      in: path
      description: 条目 ID
      required: true
      schema:
        type: integer
    ep_id:
      name: id
      in: path
      description: 章节 ID
      required: true
      schema:
        type: integer
    ep_status:
      name: status
      in: path
      description: 收视类型，参考 [EpStatus](#model-EpStatus)
      required: true
      schema:
        $ref: '#/components/schemas/EpStatus'
    responseGroup:
      name: responseGroup
      in: query
      description: 返回数据大小，参考 [ResponseGroup](#model-ResponseGroup)
        <br> 默认为 small
      required: false
      schema:
        $ref: '#/components/schemas/ResponseGroup'