10 KiB
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。
目录与路径结构
目录
文档目录以 Markdown无序列表 语法写在 README.md 中，使用缩进标识文档的层级，如视频下存在基本信息、快照、推荐等子分类，使用 Markdown 复选框 语法该标注文档是否编写完成
- [x] 视频
- [x] 基本信息
- [x] 快照
- [x] 推荐
路径
路径层级应当与文档目录一致，以文件夹的形式存放在项目中的/docs路径下，命名统一使用英文，如video、danmaku、comment
二级、三级路径应当存在二级三级目录，以README.md的形式
文件
各个子接口集整理为 md 文件，命名统一使用英文，如info.md、action.md、list.md
文档文件中用于存放相关的接口的说明，如video/下的info.md，存在查询视频基本信息、查询视频简介、查询视频分P列表等内容
Markdown文档内容格式
文档使用 Vuepress 生成，可以使用 Vuepress md 扩展语法编写
注：以下文档范式可根据实际情况进行调整
头部
文档首行为 一级标签 格式标题
文档头部不再需要手写索引
接口说明
文档中可存在多个接口说明，应当遵守同一范式，依次排列在文档中
接口说明分为标题、地址、说明、请求参数、响应正文、示例这些部分
接口标题为 二级以下 的标签，接口地址使用 引用 语法，地址只保留 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 端默认值 登录认证 |
Proto定义格式
proto 文件为 Protocol Buffers 以及 gRPC 的数据结构体定义，多用于客户端的接口，本文档也做相关的收集
存放于项目的/grpc_api路径下，使用包名进行路径层级的组织，如
/grpc_api/bilibili/main/community/reply/v1/reply.proto
/grpc_api/bilibili/app/archive/v1/archive.proto
/grpc_api/bilibili/app/view/v1/view.proto
proto 文件内使用 单行注释 标注字段或对象的含义，如
// UP主信息
message Author {
// UP主mid
int64 mid = 1;
// UP主昵称
string name = 2;
// UP主头像url
string face = 3;
}
文档提交
TODO
Issue与社群讨论
对文档内容存在不理解之处、以及发现文档内容有所缺失或错误，可直接提出，强烈建议以发 Issue 的形式参与用户反馈，并希望关于本项目的各种交流都是公开进行的，因为这样才可以保证关键信息的一致性。
由于本项目属于文档型项目，故不设置 Issue 模板，同时允许中英文标题，但提交 Issue 请遵守以下原则：
- 标题言简意骇，说明欲提出的问题要点，如
如何通过xx接口获取yy、xx接口地址已失效、关于xx字段意义的探讨、建议将xx加入yy分类等标题；切勿使用表意含糊不清或索取性的标题，如怎么解决风控、补充、搜索的接口是什么、好兄弟有没有投稿的接口等标题 - Issue 正文应对问题进行尽可能详细的描述，展开并聚焦有关的信息，例如：“在前端页面某地址 / APP 某界面会访问某 API（标明地址），它的某参数与文档中不符（标明文档地址）”
- 提出问题时注意 提问的智慧 并且 别像弱智一样提问
同时，你还可以通过加入社群的方式参与讨论（包括但不限于本项目
-
QQ 交流群：邀请链接
-
Telegram 交流群：@bilibili_API_collect_community
注意：群内讨论同样需要遵守公开交流的原则，以及群内会定期清理不活跃成员