openapi: 3.0.0
info:
  title: Bangumi API
  description: "你可以在 <https://api.bgm.tv/v0/oauth/> 生成一个 Access Token\n建议客户端开发者指定一个带有 APP 名称和版本的 User Agent，而非使用 HTTP 请求库默认的 UA"
  version: "dev"
  contact:
    name: Bangumi API
    url: https://github.com/bangumi/api/
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:
      deprecated: true
      tags:
        - 用户
      summary: 用户收藏
      parameters:
        - $ref: "#/components/parameters/username"
        - name: cat
          in: query
          description: 收藏类型
            <br> watching = 在看的动画与三次元条目
            <br> all_watching = 在看的动画三次元与书籍条目
          required: true
          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
        - name: responseGroup
          in: query
          description: medium / small
            <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
                    subject_id:
                      description: 章节 ID
                      type: integer
                    ep_status:
                      description: 完成话数
                      type: integer
                    vol_status:
                      description: 完成卷数（书籍）
                    lasttouch:
                      description: 上次更新时间
                      type: integer
                    subject:
                      allOf:
                        - $ref: "#/components/schemas/SubjectBase"
                        - type: object
                          properties:
                            eps:
                              description: 话数
                              type: integer
                              example: 27
                            eps_count:
                              description: 话数
                              type: integer
                              example: 27
                            collection:
                              $ref: "#/components/schemas/SubjectCollection"
  /user/{username}/collections/{subject_type}:
    get:
      deprecated: true
      tags:
        - 用户
      summary: 用户收藏概览
      parameters:
        - $ref: "#/components/parameters/username"
        - name: subject_type
          in: path
          description: 条目类型，详见 [SubjectTypeName](#model-SubjectTypeName)
          required: true
          schema:
            $ref: "#/components/schemas/SubjectTypeName"
        - $ref: "#/components/parameters/app_id"
        - name: max_results
          in: query
          description: 显示条数
            <br> 最多 25
          schema:
            type: integer
            maximum: 25
      responses:
        200:
          description: 获取用户指定类型的收藏概览，固定返回最近更新的收藏，不支持翻页
          content:
            application/json:
              schema:
                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:
                          status:
                            $ref: "#/components/schemas/CollectionStatus"
                          count:
                            type: integer
                          list:
                            type: array
                            items:
                              type: object
                              properties:
                                subject_id:
                                  description: 条目 ID
                                  type: string
                                subject:
                                  $ref: "#/components/schemas/SubjectBase"
  /user/{username}/collections/status:
    get:
      deprecated: true
      tags:
        - 用户
      summary: 用户收藏统计
      parameters:
        - $ref: "#/components/parameters/username"
        - $ref: "#/components/parameters/app_id"
      responses:
        200:
          description: 获取用户所有收藏信息
          content:
            application/json:
              schema:
                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:
                          status:
                            $ref: "#/components/schemas/CollectionStatus"
                          count:
                            type: integer
  /user/{username}/progress:
    get:
      deprecated: true
      tags:
        - 用户
      summary: 用户收视进度
      parameters:
        - $ref: "#/components/parameters/username"
        - name: subject_id
          in: query
          description: 条目 ID
            <br> 获取指定条目收视进度
          schema:
            type: integer
      responses:
        200:
          description: 返回用户收视进度
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    subject_id:
                      description: 条目 ID
                      type: integer
                    eps:
                      description: 章节列表
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            description: 章节 ID
                            type: integer
                          status:
                            type: object
                            properties:
                              id:
                                $ref: "#/components/schemas/EpStatusId"
                              css_name:
                                type: string
                                example: Watched
                              url_name:
                                $ref: "#/components/schemas/EpStatusType"
                              cn_name:
                                $ref: "#/components/schemas/EpStatusName"
        401:
          description: 未授权
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusCode"
      security:
        - OptionalHTTPBearer: []
  /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: 成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusCode"
        401:
          description: 未授权
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusCode"
      security:
        - HTTPBearer: []
    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: 成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusCode"
        401:
          description: 未授权
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusCode"
      security:
        - HTTPBearer: []
  /subject/{subject_id}/update/watched_eps:
    post:
      tags:
        - 进度
      summary: 批量更新收视进度
      parameters:
        - $ref: "#/components/parameters/subject_id"
        - name: watched_eps
          in: query
          description: 如看到 123 话则 POST `123`
            <br> 书籍条目传 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: 成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusCode"
        401:
          description: 未授权
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusCode"
      security:
        - HTTPBearer: []
  /collection/{subject_id}:
    get:
      tags:
        - 收藏
      summary: 获取指定条目收藏信息
      parameters:
        - $ref: "#/components/parameters/subject_id"
      responses:
        200:
          $ref: "#/components/responses/Collection"
        400:
          description: 用户未收藏该条目
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusCode"
        401:
          description: 未授权
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusCode"
      security:
        - OptionalHTTPBearer: []
  /collection/{subject_id}/{action}:
    post:
      tags:
        - 收藏
      summary: 管理收藏
      description: "管理收藏。Content-type必须为multipart/form-data或application/x-www-form-urlencoded，参数都得放在body里。"
      requestBody:
        description: "必须是content-type对应的形式，不能采用Raw"
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                status:          # <!--- form field name
                  $ref: "#/components/schemas/CollectionStatusType"
                  description: 收藏状态，参考 [CollectionStatusType](#model-CollectionStatusType)
                comment:
                  type: string
                  description: 简评
                tags:    # <!--- form field name
                  type: string
                  description: 标签
                              <br> 以半角空格分割
                rating:    # <!--- form field name
                  type: integer
                  description: 评分
                              <br> 1-10
                              <br> 不填默认重置为未评分
                privacy:    # <!--- form field name
                  type: integer
                  description: 收藏隐私
                              <br> 0 = 公开
                              <br> 1 = 私密
                              <br> 不填默认为0
              required:
                - status
      
      parameters:
        - $ref: "#/components/parameters/subject_id"
        - name: action
          in: path
          description: 收藏动作
            <br> create = 添加收藏
            <br> update = 更新收藏
            <br> 可以统一使用 `update`，系统会自动判断需要新建还是更新收藏
          required: true
          schema:
            type: string
            enum:
              - create
              - update
              
      responses:
        200:
          $ref: "#/components/responses/Collection"
        401:
          description: 未授权
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusCode"
      security:
        - HTTPBearer: []
components:
  schemas:
    CollectionStatusId:
      description: 收藏状态 ID
      type: integer
      enum:
        - 1
        - 2
        - 3
        - 4
        - 5
      example: 5
    CollectionStatusType:
      description: 收藏状态类型
      type: string
      enum:
        - wish
        - collect
        - do
        - on_hold
        - dropped
      example: dropped
    CollectionStatusName:
      description: 收藏状态名称
      type: string
      enum:
        - 想做
        - 做过
        - 在做
        - 搁置
        - 抛弃
      example: 抛弃
    CollectionStatus:
      description: 收藏状态
        <br> 1 = wish = 想做
        <br> 2 = collect = 做过
        <br> 3 = do = 在做
        <br> 4 = on_hold = 搁置
        <br> 5 = dropped = 抛弃
      type: object
      properties:
        id:
          $ref: "#/components/schemas/CollectionStatusId"
        type:
          $ref: "#/components/schemas/CollectionStatusType"
        name:
          $ref: "#/components/schemas/CollectionStatusName"
    EpStatusId:
      description: 章节状态 ID
      type: integer
      enum:
        - 2
        - 1
        - 3
    EpStatusType:
      description: 章节状态类型
      type: string
      enum:
        - watched
        - queue
        - drop
        - remove
    EpStatusName:
      description: 章节状态名称
      type: string
      enum:
        - 看过
        - 想看
        - 抛弃
        - 撤销
    ResponseGroup:
      description: 返回数据大小
      type: string
      enum:
        - small
        - medium
      default: small
    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
    SubjectCollection:
      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
    Subject:
      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: ちょびっツ
    SubjectBase:
      allOf:
        - $ref: "#/components/schemas/Subject"
        - type: object
          properties:
            name_cn:
              description: 条目中文名称
              type: string
              example: 人形电脑天使心
            summary:
              description: 剧情简介
              type: string
              example: 在不久的将来,电子技术飞速发展,电脑成为人们生活中不可缺少的一部分.主角的名字是本须和秀树,是个19岁的少年,由于考试失败,来到东京上补习班,过着贫穷潦倒的生活……\r\n到达东京的第一天,他很幸运的在垃圾堆捡到一个人型电脑,一直以来秀树都非常渴望拥有个人电脑.当他抱着她带返公寓后,却不知如何开机,在意想不到的地方找到开关并开启后,故事就此展开\r\n本须和秀树捡到了人型计算机〔唧〕。虽然不晓得她到底是不是〔Chobits〕，但她的身上似乎藏有极大的秘密。看到秀树为了钱而烦恼，唧出去找打工，没想到却找到了危险的工作！为了让秀树开心，唧开始到色情小屋打工。但她在遭到过度激烈的强迫要求之后失控。让周遭计算机因此而强制停摆。\r\n另一方面，秀树发现好友新保与补习班的清水老师有着不可告人的关系……
            air_date:
              description: 放送开始日期
              type: string
              example: "2002-04-02"
            air_weekday:
              description: 放送星期
              type: integer
              example: 2
            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
    SubjectSmall:
      allOf:
        - $ref: "#/components/schemas/SubjectBase"
        - type: object
          properties:
            eps:
              description: 话数
              type: integer
              example: 27
            eps_count:
              description: 话数
              type: integer
              example: 27
            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
            collection:
              $ref: "#/components/schemas/SubjectCollection"
    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!
        usergroup:
          $ref: "#/components/schemas/UserGroup"
    UserGroup:
      description: >-
        用户组
        <br> 1 = 管理员
        <br> 2 = Bangumi 管理猿
        <br> 3 = 天窗管理猿
        <br> 4 = 禁言用户
        <br> 5 = 禁止访问用户
        <br> 8 = 人物管理猿
        <br> 9 = 维基条目管理猿
        <br> 10 = 用户
        <br> 11 = 维基人
      type: integer
      enum:
        - 1
        - 2
        - 3
        - 4
        - 5
        - 8
        - 9
        - 10
        - 11
      example: 11
    StatusCode:
      description: 响应状态（HTTP 状态码都为 200）
      type: object
      properties:
        request:
          description: 当前请求的地址
          type: string
        code:
          description: >-
            状态码
            <br> 200 OK
            <br> 202 Accepted
            <br> 304 Not Modified
            <br> 30401 Not Modified: Collection already exists
            <br> 400 Bad Request
            <br> 40001 Error: Nothing found with that ID
            <br> 401 Unauthorized
            <br> 40101 Error: Auth failed over 5 times
            <br> 40102 Error: Username is not an Email address
            <br> 405 Method Not Allowed
            <br> 404 Not Found
          type: integer
          enum:
            - 200
            - 202
            - 304
            - 30401
            - 400
            - 40001
            - 401
            - 40101
            - 40102
            - 405
            - 404
        error:
          description: 状态信息
          type: string
  responses:
    Collection:
      description: 条目收藏信息
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                $ref: "#/components/schemas/CollectionStatus"
              rating:
                description: 评分
                type: integer
              comment:
                description: 评论
                type: string
              private:
                description: 收藏隐私
                type: integer
                enum:
                  - 0
                  - 1
              tag:
                description: 标签
                type: array
                items:
                  type: string
              ep_status:
                description: 完成话数
                type: integer
              lasttouch:
                description: 上次更新时间
                type: integer
              user:
                $ref: "#/components/schemas/User"
  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: 收视类型，参考 [EpStatusType](#model-EpStatusType)
      required: true
      schema:
        $ref: "#/components/schemas/EpStatusType"
    responseGroup:
      name: responseGroup
      in: query
      description: 返回数据大小，参考 [ResponseGroup](#model-ResponseGroup)
        <br> 默认为 small
      required: false
      schema:
        $ref: "#/components/schemas/ResponseGroup"
    app_id:
      name: app_id
      in: query
      description: >-
        [https://bgm.tv/dev/app](https://bgm.tv/dev/app) 申请到的 App ID
      required: true
      schema:
        type: string
  securitySchemes:
    OptionalHTTPBearer:
      type: "http"
      description: |
        Some api like getting a subject doesn't require any authorization. 
        But only authorized user can see NSFW recoed, non-authorized user get 404 response.
        You can create a access token here [https://bgm.tv/dev/app](https://bgm.tv/dev/app)
      scheme: "bearer"

    HTTPBearer:
      type: "http"
      description: "require a authorization"
      scheme: "bearer"