为本项目添加一种可移植 API 标记语言，并以此重构
SocialSisterYi opened this issue · comments
原因
目前本项目仅使用 MarkDown 文档描述各 API 使用方法及其消息体字段，不易移植为适用各编程语言的 SDK，也缺乏格式标准，同时无法做到规范社区提交。
提议
现社区提议构建一种类 ProtoBuf 的标记语言AML(API Mark Language)以此重构 b-a-c Project，使其可以被序列化 / 反序列化，编译为各语言的 SDK 以及各种人类友好的文档格式。
flag立下了.jpg
有可以参考的项目吗
有道理，可以开branch了 肝准备好了 :D
结果一周了连branch都还没开.jpg
#查询进度
#查询进度
咕咕咕（最近真的太忙了，以及马上要开学了
#查询进度
咕咕咕（最近真的太忙了，以及马上要开学了
我明天也要开学了555
本质是XML文件？
本质是XML文件？
并不是 XML 文件，而是一种全新的描述语言格式，类似 OPENAPI3.0 文档，但并不以 JSON 作为载体，而是参考 protobuf 的 proto 格式，并在它的基础上加入更只能的类型系统，以及对 REST API 友好的 Server 定义
唉，我的mihoyo-api-collect项目也遇到这个棘手的问题……Markdown的api文档太难维护了……
应该可以用 postman 或者类似的工具吧，可以直接生成文档和各种语言的请求示例
随便写的一个库 go-api-markup-language 看看是否满足这里提出的想法？
随便写的一个库 go-api-markup-language 看看是否满足这里提出的想法？
弄了个根据他的规范文档解析的半成品TypeScript库
随便写的一个库 go-api-markup-language 看看是否满足这里提出的想法？
支持，如果可以支持i18n那就是极好的了
随便写的一个库 go-api-markup-language 看看是否满足这里提出的想法？
支持，如果可以支持i18n那就是极好的了
有规范相关的建议吗？比如文件的格式、需要支持什么功能？
有规范相关的建议吗？比如文件的格式、需要支持什么功能？
我对这方面其实也不是非常了解，需要支持i18n，也就是文档提供多语言支持
顺便更新一下文档，部分文档介绍的接口是老接口，哔哩哔哩已有更新接口。新接口部分必要参数已更新。
我个人非常建议直接基于现有的 PostMan/PostWoman 等项目的 Collection 导出文件生成 API 文档，这种方式非常利于编辑，自动化测试，以及生成 SDK
搞个像dumi那样的工具，既能生成文档网站，又能生成sdk
推荐ApiPost编辑文档，对标postman，但更具创新。可以导出Markdown，doc文档等，亦可生成在线文档。可离线测试接口数据，避免登录。人性化使用，避免复杂逻辑，操作简单，适合高强度迅速开发。并支持更多接口协议，免费使用。（狗头保命）
我看bilibili-api 里面用json来管理，感觉这个挺不错的（）
我看bilibili-api 里面用json来管理，感觉这个挺不错的（）
烂透了，你仔细看看我发过的issue就知道了，根本不适合做注释
{"params":{"type": "int: 1 video 2 article 3 audio 0 all"}}
这种抽象玩意，我写的难受，读的人也难受
想改，我也没啥思路，本来说 pydantic 也搁置没空
我看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": "用户基本信息" }, 这样感觉怎么样
我看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，评价是纯差评
我看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
我看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也可以转文档
我看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也可以转文档
不清楚，不予评价
可以定一个方法吗，我实在太想重构 bilibili-api 库了，但是不知道用什么方式记录 api 信息最合适
Swagger
大佬对Swagger2有没有兴趣？我对实现的技术栈不了解，不过我用过成品来输出SDK，感觉手感很好，yaml转SDK和doc都可以
我也感觉swagger的那种openapidocs形式的好
我这两天先试试写一部分的 swagger 里那种 openapi3 风格的内容出来，然后再让社区的大家都评价一下来
openapi generator 这个也可以参考看看