-
-
Notifications
You must be signed in to change notification settings - Fork 1.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
为本项目添加一种可移植 API 标记语言,并以此重构 #604
Comments
flag立下了.jpg |
有可以参考的项目吗 |
有道理,可以开branch了 肝准备好了 :D |
结果一周了连branch都还没开.jpg |
#查询进度 |
咕咕咕(最近真的太忙了,以及马上要开学了 |
我明天也要开学了555 |
本质是XML文件? |
并不是 XML 文件,而是一种全新的描述语言格式,类似 OPENAPI3.0 文档,但并不以 JSON 作为载体,而是参考 protobuf 的 proto 格式,并在它的基础上加入更只能的类型系统,以及对 REST API 友好的 Server 定义 |
唉,我的mihoyo-api-collect项目也遇到这个棘手的问题……Markdown的api文档太难维护了…… |
应该可以用 postman 或者类似的工具吧,可以直接生成文档和各种语言的请求示例 |
随便写的一个库 go-api-markup-language 看看是否满足这里提出的想法? |
弄了个根据他的规范文档解析的半成品TypeScript库 |
支持,如果可以支持i18n那就是极好的了 |
有规范相关的建议吗?比如文件的格式、需要支持什么功能? |
我对这方面其实也不是非常了解,需要支持i18n,也就是文档提供多语言支持 |
顺便更新一下文档,部分文档介绍的接口是老接口,哔哩哔哩已有更新接口。新接口部分必要参数已更新。 |
我个人非常建议直接基于现有的 PostMan/PostWoman 等项目的 Collection 导出文件生成 API 文档,这种方式非常利于编辑,自动化测试,以及生成 SDK |
搞个像dumi那样的工具,既能生成文档网站,又能生成sdk |
推荐ApiPost编辑文档,对标postman,但更具创新。可以导出Markdown,doc文档等,亦可生成在线文档。可离线测试接口数据,避免登录。人性化使用,避免复杂逻辑,操作简单,适合高强度迅速开发。并支持更多接口协议,免费使用。(狗头保命) |
我看bilibili-api 里面用json来管理,感觉这个挺不错的() |
烂透了,你仔细看看我发过的issue就知道了,根本不适合做注释
这种抽象玩意,我写的难受,读的人也难受 想改,我也没啥思路,本来说 pydantic 也搁置没空 |
我看他的json是这样写的(其实主要不是文档的作用,是解析完调用爬取) |
很遗憾我是这个库的 contributor,评价是纯差评 |
这样嘛T.T |
那Swagger怎么样owo,基于yaml/json,可以转SDK也可以转文档 |
不清楚,不予评价 |
可以定一个方法吗,我实在太想重构 bilibili-api 库了,但是不知道用什么方式记录 api 信息最合适 |
大佬对Swagger2有没有兴趣?我对实现的技术栈不了解,不过我用过成品来输出SDK,感觉手感很好,yaml转SDK和doc都可以 |
我也感觉swagger的那种openapidocs形式的好 |
openapi generator 这个也可以参考看看 |
swagger 适合api提供方,通过语法分析,基于代码自动生成. 真要手写swagger 的json 或yaml,是及其反人类的.
|
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本身确实挺要命,也许可以搞个转换器出来 |
各种api框架都是支持从 相较于 直接写 swagger json & yaml优点是:
我用过比较好用的是
都是写完代码直接跑就是api文档, 无需额外配置或生成操作, 也支持自定义css, 改文档样式. |
...考虑下存量吧,逆天。谁这么闲去挨个糊 typing。这问题无解,成本太高 |
如果用大语言模型基于现有的markdown去做呢? 因为我看现有的文档,虽然是按照一定格式去编写的,但是格式并没有严格到可以直接自动化读取成数据的程度。我能想到省事的重构方法就是用gpts 做一个文档阅读助手之类的东西,帮助生成代码,json什么的。(gpt前阵子出了一个json生成的功能) 亦或是对现有文档挨个检查,严格遵循某种格式。(这个工作量小一些)然后读取为元数据,再生成文档。 |
哪个工作量都是一坨...都得人工 review,其实没谁在乎用啥办法存接口,只是没人去标准化这坨 md 罢了...等个雅利安超人 |
彳亍口巴 |
用 openapi + LLM 是非常合理的选择。我一直在考虑使用这个方案,根据这个 repo 实现一个 fastapi 版本的符合 openapi 规范的服务器。看上去工作量并不大,但是我还有很多其他工作要处理,一直处于搁置状态( |
#查询进度 |
我新建文件夹了 |
有点幽默了 |
尝试了一下,完全可行。 我现在正在使用 Gemini Advanced 进行生成。在第一个版本,我会将所有 api 放在一个 openapi 3.0 yaml 文件中,这样比较适合 LLM 生成。不过有很多地方需要手动操作,所以没有那么快端出来。预计今晚能搞完。 |
成了 90%。还剩了点接口没做, LLM 额度爆了,姑且先分享。 项目地址:https://github.com/Jannchie/bilibili-openapi |
能请教你一个问题吗,大能。 这wbi_sign我使用开源代码里的(WBI.py)代码计算出来,填进去。然后发送请求返回412.请问是什么问题呢? |
我没有测过需要签名的接口。有很多种可能,比如请求 search query 顺序和计算 wbi_sign 时不一样,也可能是因为其他风控策略,比如没有伪装 User-Agent 被 Ban。 |
wbi 问题请另行前往相关 issue |
原因
目前本项目仅使用 MarkDown 文档描述各 API 使用方法及其消息体字段,不易移植为适用各编程语言的 SDK,也缺乏格式标准,同时无法做到规范社区提交。
提议
现社区提议构建一种类 ProtoBuf 的标记语言
AML(API Mark Language)
以此重构 b-a-c Project,使其可以被序列化 / 反序列化,编译为各语言的 SDK 以及各种人类友好的文档格式。The text was updated successfully, but these errors were encountered: