为本项目添加一种可移植 API 标记语言，并以此重构
SocialSisterYi opened this issue · 49 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 这个也可以参考看看
swagger 适合api提供方,通过语法分析,基于代码自动生成. 真要手写swagger 的json 或yaml,是及其反人类的.
我看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也可以转文档
swagger(openapi)并不反人类。
看官网给的Path对象例子也看得出还是很易读和编写的。
paths:
/devices:
get:
tags:
- Device
description: returns all registered devices
operationId: getDevices
parameters:
- in: query
name: skip
description: number of records to skip
schema:
type: integer
format: int32
- in: query
name: limit
description: max number of records to return
schema:
type: integer
format: int32
responses:
'200':
description: All the devices
content:
application/json:
schema:
type: array
items:
type: string
format: uri
example: 'http://10.0.0.225:8080'显然需要能自动生成…无论是从手写本身麻烦还是存量接口角度
不是给人用的…
显然需要能自动生成…无论是从手写本身麻烦还是存量接口角度
不是给人用的…
从yaml到可用的doc和api接口是挺好用的，但是写yaml本身确实挺要命，也许可以搞个转换器出来
显然需要能自动生成…无论是从手写本身麻烦还是存量接口角度
不是给人用的…从yaml到可用的doc和api接口是挺好用的，但是写yaml本身确实挺要命，也许可以搞个转换器出来
各种api框架都是支持从代码 到 swagger json&yaml 再到 交互式文档 生成的. 一个可能的办法是用代码定义好 端点 和 实体类, 然后直接出swagger json&yaml, 并生成可部署的交互式文档出来.
相较于 直接写 swagger json & yaml优点是:
- 代码对编写者更友好
- 可以分文件定义, 合并分支的时候方便
我用过比较好用的是
- python的fastapi,
- c#的asp.net,
都是写完代码直接跑就是api文档, 无需额外配置或生成操作, 也支持自定义css, 改文档样式.
这种方式是否可行?
...考虑下存量吧，逆天。谁这么闲去挨个糊 typing。这问题无解，成本太高
...考虑下存量吧，逆天。谁这么闲去挨个糊 typing。这问题无解，成本太高
如果用大语言模型基于现有的markdown去做呢？
因为我看现有的文档，虽然是按照一定格式去编写的，但是格式并没有严格到可以直接自动化读取成数据的程度。我能想到省事的重构方法就是用gpts 做一个文档阅读助手之类的东西，帮助生成代码，json什么的。（gpt前阵子出了一个json生成的功能）
亦或是对现有文档挨个检查，严格遵循某种格式。（这个工作量小一些）然后读取为元数据，再生成文档。
哪个工作量都是一坨...都得人工 review，其实没谁在乎用啥办法存接口，只是没人去标准化这坨 md 罢了...等个雅利安超人
彳亍口巴
用 openapi + LLM 是非常合理的选择。我一直在考虑使用这个方案，根据这个 repo 实现一个 fastapi 版本的符合 openapi 规范的服务器。看上去工作量并不大，但是我还有很多其他工作要处理，一直处于搁置状态（