github-repos/bilibili-API-collect

Fork 0

mirror of https://github.com/SocialSisterYi/bilibili-API-collect.git synced 2024-12-27 04:50:12 +08:00

SocialSisterYi 75ee9d976e

update【contributing】

2023-01-21 22:18:45 +08:00

9.3 KiB

Raw Blame History

bilibili-API-collect

欢迎来到 bilibili-API-collect 社区贡献指南，本文主要面向需要进行提交贡献文档内容的用户。

总则

bilibili-API-collect 项目（简称 BAC 或 b-a-c）是一个仅用于学习研究、社区开源、公益性质的 B站（哔哩哔哩） API（应用程序接口）文档，使用 CC-BY-NC 4.0 协议开源，它将无差别收集整理相关的主站业务接口。

该项目使用 MarkDown 语法进行文档书写，按照业务类型及功能以路径 + 文件形式索引，任何用户都可通过 Pull Request 提供自己分析出的接口地址与使用说明。

本项目收集的接口类型包括但不限于 REST API、gRPC、WebSocket，文档内统一优先使用安全套接字协议，如https、securityRpc、wss。

目录与路径结构

路径

路径层级应当与文档目录一致，以文件夹的形式存放在项目中，命名统一使用英文，如video、danmaku、comment

二级、三级路径应当存在二级三级目录，以README.md的形式

文件

各个子接口集整理为 md 文件，命名统一使用英文，如info.md、action.md、list.md

文档文件中用于存放相关的接口的说明，如video/下的info.md，存在查询视频基本信息、查询视频简介、查询视频分P列表等内容

文档内容格式

注：以下文档范式可根据实际情况进行调整

头部

文档首行为 一级标签 格式标题

标题下方为索引，与正文二级标题对应，使用列表语法与缩进，每项使用 超链接 语法实现 id 锚点跳转

头部结束应使用 分隔线 语法划线分割

# 视频

- [获取视频详细信息](#获取视频详细信息)
- [获取视频简介](#获取视频简介)

---

接口说明

文档中可存在多个接口说明，应当遵守同一范式，依次排列在文档中

接口说明分为标题、地址、说明、请求参数、响应正文、示例这些部分

接口标题为 二级以下 的标签，接口地址使用引用语法，地址只保留 REST API 路径，不应携带 query 等内容

接口地址下方需要注明接口的请求方式，如GET、POST、PUT等，使用斜体语法

若接口存在认证或鉴权，需要在说明中注明，如Cookie(SESSDATA)、APP（认证是针对用户的，鉴权是针对接口使用的

其他使用说明也可写在这里，如限制游客访问的视频需要登录

eg：

## 获取视频详细信息_web端

> https://api.bilibili.com/x/web-interface/view

*请求方式：GET*

认证方式：Cookie(SESSDATA)

限制游客访问的视频需要登录

请求参数应在接口说明的下方，应注明参数类型 url 参数或正文参数（正文参数应注明 content-type，如application/x-www-form-urlencoded或multipart/form-data），使用加粗语法

对象的字段及其含义使用表格进行整理，表头统一为参数名、类型、内容、必要性、备注，类型为num、str、bool、nums、strs、file等，必要性为必要、非必要、必要(可选)等，表格内每个字段为一行

eg：

参数名	类型	内容	必要性	备注
aid	num	稿件 avid	必要 (可选)	avid 与 bvid 任选
bvid	str	稿件 bvid	必要 (可选)	avid 与 bvid 任选

响应正文应在请求参数的下方，接口响应的数据格式应标注，如JSON回复、XML回复、Protobuf回复，使用加粗语法

json object 或 protobuf message 应以对象的表格形式书写，表头为根对象或xx中的yy对象，若对象位于数组中为xx数组中的对象

表头统一为字段、类型、内容、备注，类型为 JSON / Protobuf 的标准类型

不明确定义的字段说明在末尾添加问号，如播放数？；定义尚未明确的字段使用问号包于括号中占位，如（？）

多个对象及数组，使用遍历树的顺序进行排列

eg：

data对象：

字段	类型	内容	备注
bvid	str	稿件 bvid
aid	num	稿件 avid
videos	num	稿件分P总数	默认为 1
tid	num	分区 tid

json array 或 protobuf repeated 类型使用数组的表格形式书写，表头统一为项、类型、内容、备注，无限长度数组表尾需要添加省略号

数组每项内容若与实际数据有关联，内容字段则可标为(n+1)P 视频内容这样的形式

eg：

data中的pages数组：

项	类型	内容	备注
0	obj	1P 视频内容	无分P仅有此项
n	obj	(n+1)P 视频内容
……	obj	……	……

示例部分位于所有响应正文部分下方，需要加粗格式，分为请求命令示例与响应体示例两部分

请求命令示例为一段可测试该接口的 curl 命令或 Python 脚本，使用 代码块 语法书写，命令应当尽可能简短、便于使人阅读

示例命令中的认证信息应做脱敏处理，如 Cookie、Token、access_key 等，可替换为xxx占位

示例命令前后可以适当添加一些文字说明

响应体示例为一段格式化后的 JSON 或 protobuf message，使用 代码块 语法书写，并使用<details>标签进行折叠

eg：

示例：

获取视频av85440373的基本信息

curl -G 'https://api.bilibili.com/x/web-interface/view' \
	--data-urlencode 'aid=85440373'

<details>
<summary>查看响应示例：</summary>

{
  "code": 0,
  "message": "0",
  "ttl": 1,
  "data": {
    "bvid": "BV117411r7R1",
    "aid": 85440373,
    "videos": 1,
    "tid": 28,
    "tname": "原创音乐",
    "copyright": 1,
    ...

</details>

枚举值与属性位

接口返回或请求中若存在一些 enum 类型或二进制属性位，应当单独进行探讨，如视频的属性位attribute或视频清晰度qn

这些值及其说明使用表格进行整理，表头统一为位 / 代码 / 值、含义、备注

这些枚举值或属性位的用法应附加文字说明

eg：

值	含义	备注
6	240P 极速	仅 MP4 格式支持仅`platform=html5`时有效
16	360P 流畅
32	480P 清晰
64	720P 高清	WEB 端默认值 B站前端需要登录才能选择，但是直接发送请求可以不登录就拿到 720P 的取流地址无 720P 时则为 720P60
74	720P60 高帧率	登录认证
80	1080P 高清	TV 端与 APP 端默认值登录认证

文档提交

TODO

Issue与社群讨论

对文档内容存在不理解之处、以及发现文档内容有所缺失或错误，可直接提出，强烈建议以发 Issue 的形式参与用户反馈，并希望关于本项目的各种交流都是公开进行的，因为这样才可以保证关键信息的一致性。

由于本项目属于文档型项目，故不设置 Issue 模板，同时允许中英文标题，但提交 Issue 请遵守以下原则：

标题言简意骇，说明欲提出的问题要点，如如何通过xx接口获取yy、xx接口地址已失效、关于xx字段意义的探讨、 建议将xx加入yy分类等标题；切勿使用表意含糊不清或索取性的标题，如怎么解决风控、补充、搜索的接口是什么、好兄弟有没有投稿的接口等标题
Issue 正文应对问题进行尽可能详细的描述，展开并聚焦有关的信息，例如：“在前端页面某地址 / APP 某界面会访问某 API（标明地址），它的某参数与文档中不符（标明文档地址）”
提出问题时注意提问的智慧并且别像弱智一样提问

同时，你还可以通过加入社群的方式参与讨论（包括但不限于本项目

QQ 交流群：邀请链接
Telegram 交流群：@bilibili_API_collect_community

注意：群内讨论同样需要遵守公开交流的原则，以及群内会定期清理不活跃成员

9.3 KiB Raw Blame History Unescape Escape