Northern_Lights/bilibili-API-collect
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
392dc2b0be
bilibili-API-collect/CONTRIBUTING.md
wuziqian211 392dc2b0be
Update CONTRIBUTING.md
2024-05-03 15:51:03 +08:00

11 KiB
Raw Blame History

贡献指南

欢迎来到 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。

Issue 与社群讨论

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

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

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

同时，您还可以通过加入社群的方式参与讨论

::: tip ✅提示

QQ 交流群为综合技术交流群（兼 Owner 的粉丝群），可交流探讨任何技术，包括但不限于 BAC 项目

Telegram 交流群主要用作 BAC 项目的 Github Bot 接收，也可以进行项目相关的讨论，但不建议在此讨论交流其他内容（公开群）

:::

::: warning ⚠️注意

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

QQ 交流群的加群问题答案可以去 Owner 的主页 Contact 部分找到，如果您填写“我不知道，从 Github 来的“那么管理员将有理由禁止您进群讨论！

:::

::: danger 🈲禁止

项目 Issue 及其相关社群中禁止询问讨论 风控解除、爬虫（采集）、破解、漏洞利用、买卖代码和账号 相关内容，抵制基于本项目进行的一切黑产行为！

:::

目录与路径结构

目录

文档目录以 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` 的基本信息

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

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

```jsonc
{
  "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