为本项目添加一种可移植 API 标记语言，并以此重构

[SocialSisterYi]

原因

目前本项目仅使用 MarkDown 文档描述各 API 使用方法及其消息体字段，不易移植为适用各编程语言的 SDK，也缺乏格式标准，同时无法做到规范社区提交。

提议

现社区提议构建一种类 ProtoBuf 的标记语言AML(API Mark Language)以此重构 b-a-c Project，使其可以被序列化 / 反序列化，编译为各语言的 SDK 以及各种人类友好的文档格式。

[catlair]

flag立下了.jpg

[7rikka]

有可以参考的项目吗

[fred913]

有道理，可以开branch了 肝准备好了 :D

[Nemo2011]

结果一周了连branch都还没开.jpg

[MineCreeper86]

#查询进度

[SocialSisterYi]

#查询进度

咕咕咕（最近真的太忙了，以及马上要开学了

[MineCreeper86]

#查询进度

咕咕咕（最近真的太忙了，以及马上要开学了

我明天也要开学了555

[MoRanYue]

本质是XML文件？

[SocialSisterYi]

本质是XML文件？

并不是 XML 文件，而是一种全新的描述语言格式，类似 OPENAPI3.0 文档，但并不以 JSON 作为载体，而是参考 protobuf 的 proto 格式，并在它的基础上加入更只能的类型系统，以及对 REST API 友好的 Server 定义

[MoRanYue]

唉，我的mihoyo-api-collect项目也遇到这个棘手的问题……Markdown的api文档太难维护了……

[Jannchie]

应该可以用 postman 或者类似的工具吧，可以直接生成文档和各种语言的请求示例

[Drelf2018]

随便写的一个库 go-api-markup-language 看看是否满足这里提出的想法？

[MoRanYue]

随便写的一个库 go-api-markup-language 看看是否满足这里提出的想法？

弄了个根据他的规范文档解析的半成品TypeScript库

仓库：https://github.com/Kamisato-Ayaka-233/ApiMarkupLanguage

[xiaoyv404]

随便写的一个库 go-api-markup-language 看看是否满足这里提出的想法？

支持，如果可以支持i18n那就是极好的了

[Drelf2018]

随便写的一个库 go-api-markup-language 看看是否满足这里提出的想法？

支持，如果可以支持i18n那就是极好的了

有规范相关的建议吗？比如文件的格式、需要支持什么功能？

[xiaoyv404]

有规范相关的建议吗？比如文件的格式、需要支持什么功能？

我对这方面其实也不是非常了解，需要支持i18n，也就是文档提供多语言支持

[Sualiu]

顺便更新一下文档，部分文档介绍的接口是老接口，哔哩哔哩已有更新接口。新接口部分必要参数已更新。

[MicroCBer]

我个人非常建议直接基于现有的 PostMan/PostWoman 等项目的 Collection 导出文件生成 API 文档，这种方式非常利于编辑，自动化测试，以及生成 SDK

[z-juln]

搞个像dumi那样的工具，既能生成文档网站，又能生成sdk

[Sualiu]

推荐ApiPost编辑文档，对标postman，但更具创新。可以导出Markdown，doc文档等，亦可生成在线文档。可离线测试接口数据，避免登录。人性化使用，避免复杂逻辑，操作简单，适合高强度迅速开发。并支持更多接口协议，免费使用。（狗头保命）

[PetterZhukov]

我看bilibili-api 里面用json来管理，感觉这个挺不错的（）

[z0z0r4]

我看bilibili-api 里面用json来管理，感觉这个挺不错的（）

烂透了，你仔细看看我发过的issue就知道了，根本不适合做注释

{"params":{"type": "int: 1 video 2 article 3 audio 0 all"}}

这种抽象玩意，我写的难受，读的人也难受

想改，我也没啥思路，本来说 pydantic 也搁置没空

[PetterZhukov]

我看bilibili-api 里面用json来管理，感觉这个挺不错的（）

烂透了，你仔细看看我发过的issue就知道了，根本不适合做注释

{"params":{"type": "int: 1 video 2 article 3 audio 0 all"}}

这种抽象玩意，我写的难受，读的人也难受

想改，我也没啥思路，本来说 pydantic 也搁置没空

我看他的json是这样写的（其实主要不是文档的作用，是解析完调用爬取） "info": { "url": "https://api.bilibili.com/x/space/wbi/acc/info", "method": "GET", "verify": false, "wbi": true, "params": { "mid": "int: uid" }, "comment": "用户基本信息" }, 这样感觉怎么样

[z0z0r4]

我看bilibili-api 里面用json来管理，感觉这个挺不错的（）

烂透了，你仔细看看我发过的issue就知道了，根本不适合做注释
{"params":{"type": "int: 1 video 2 article 3 audio 0 all"}}
这种抽象玩意，我写的难受，读的人也难受
想改，我也没啥思路，本来说 pydantic 也搁置没空

我看他的json是这样写的（其实主要不是文档的作用，是解析完调用爬取） "info": { "url": "https://api.bilibili.com/x/space/wbi/acc/info", "method": "GET", "verify": false, "wbi": true, "params": { "mid": "int: uid" }, "comment": "用户基本信息" }, 这样感觉怎么样

很遗憾我是这个库的 contributor，评价是纯差评

[PetterZhukov]

我看bilibili-api 里面用json来管理，感觉这个挺不错的（）

烂透了，你仔细看看我发过的issue就知道了，根本不适合做注释
{"params":{"type": "int: 1 video 2 article 3 audio 0 all"}}
这种抽象玩意，我写的难受，读的人也难受
想改，我也没啥思路，本来说 pydantic 也搁置没空

我看他的json是这样写的（其实主要不是文档的作用，是解析完调用爬取） "info": { "url": "https://api.bilibili.com/x/space/wbi/acc/info", "method": "GET", "verify": false, "wbi": true, "params": { "mid": "int: uid" }, "comment": "用户基本信息" }, 这样感觉怎么样

很遗憾我是这个库的 contributor，评价是纯差评

这样嘛T.T

[PetterZhukov]

我看bilibili-api 里面用json来管理，感觉这个挺不错的（）

烂透了，你仔细看看我发过的issue就知道了，根本不适合做注释
{"params":{"type": "int: 1 video 2 article 3 audio 0 all"}}
这种抽象玩意，我写的难受，读的人也难受
想改，我也没啥思路，本来说 pydantic 也搁置没空

我看他的json是这样写的（其实主要不是文档的作用，是解析完调用爬取） "info": { "url": "https://api.bilibili.com/x/space/wbi/acc/info", "method": "GET", "verify": false, "wbi": true, "params": { "mid": "int: uid" }, "comment": "用户基本信息" }, 这样感觉怎么样

很遗憾我是这个库的 contributor，评价是纯差评

那Swagger怎么样owo，基于yaml/json，可以转SDK也可以转文档

[z0z0r4]

我看bilibili-api 里面用json来管理，感觉这个挺不错的（）

烂透了，你仔细看看我发过的issue就知道了，根本不适合做注释
{"params":{"type": "int: 1 video 2 article 3 audio 0 all"}}
这种抽象玩意，我写的难受，读的人也难受
想改，我也没啥思路，本来说 pydantic 也搁置没空

我看他的json是这样写的（其实主要不是文档的作用，是解析完调用爬取） "info": { "url": "https://api.bilibili.com/x/space/wbi/acc/info", "method": "GET", "verify": false, "wbi": true, "params": { "mid": "int: uid" }, "comment": "用户基本信息" }, 这样感觉怎么样

很遗憾我是这个库的 contributor，评价是纯差评

那Swagger怎么样owo，基于yaml/json，可以转SDK也可以转文档

不清楚，不予评价

[Drelf2018]

可以定一个方法吗，我实在太想重构 bilibili-api 库了，但是不知道用什么方式记录 api 信息最合适

[PetterZhukov]

Swagger

大佬对Swagger2有没有兴趣？我对实现的技术栈不了解，不过我用过成品来输出SDK，感觉手感很好，yaml转SDK和doc都可以

[IAALAI]

我也感觉swagger的那种openapidocs形式的好
我这两天先试试写一部分的 swagger 里那种 openapi3 风格的内容出来，然后再让社区的大家都评价一下来

[eric2788]

openapi generator 这个也可以参考看看