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

SocialSisterYi · 2023-02-03T09:44:26Z

原因

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

提议

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

The text was updated successfully, but these errors were encountered:

catlair · 2023-02-06T08:52:20Z

flag立下了.jpg

7rikka · 2023-02-07T01:15:05Z

有可以参考的项目吗

fred913 · 2023-02-10T11:33:10Z

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

Nemo2011 · 2023-02-11T07:11:39Z

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

MineCreeper86 · 2023-02-14T01:48:17Z

#查询进度

SocialSisterYi · 2023-02-14T06:02:42Z

#查询进度

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

MineCreeper86 · 2023-02-14T06:03:39Z

#查询进度

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

我明天也要开学了555

MoRanYue · 2023-02-16T10:31:04Z

本质是XML文件？

SocialSisterYi · 2023-02-20T06:44:01Z

本质是XML文件？

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

MoRanYue · 2023-05-21T13:37:51Z

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

Jannchie · 2023-06-07T15:27:13Z

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

Drelf2018 · 2023-06-10T07:49:58Z

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

MoRanYue · 2023-06-23T22:51:49Z

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

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

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

xiaoyv404 · 2023-07-11T07:12:53Z

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

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

Drelf2018 · 2023-07-11T11:06:56Z

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

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

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

xiaoyv404 · 2023-07-11T11:13:49Z

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

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

Sualiu · 2023-07-27T07:31:54Z

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

std-microblock · 2023-07-27T08:29:24Z

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

z-juln · 2023-08-06T08:17:46Z

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

Sualiu · 2023-08-14T15:04:53Z

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

PetterZhukov · 2024-03-10T09:43:01Z

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

z0z0r4 · 2024-03-10T10:15:51Z

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

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

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

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

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

PetterZhukov · 2024-03-10T10:32:17Z

我看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 · 2024-03-10T14:00:20Z

我看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 · 2024-03-10T14:08:32Z

我看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 · 2024-03-10T14:13:00Z

我看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 · 2024-03-11T04:16:27Z

我看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 · 2024-04-06T17:07:53Z

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

PetterZhukov · 2024-04-06T17:10:24Z

Swagger

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

IAALAI · 2024-04-24T15:04:08Z

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

eric2788 · 2024-04-29T08:38:14Z

openapi generator 这个也可以参考看看

fengb3 · 2024-06-01T10:41:56Z

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也可以转文档

Genouka · 2024-08-17T01:15:44Z

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'

z0z0r4 · 2024-08-17T11:58:27Z

显然需要能自动生成…无论是从手写本身麻烦还是存量接口角度

不是给人用的…

PetterZhukov · 2024-08-17T12:17:04Z

显然需要能自动生成…无论是从手写本身麻烦还是存量接口角度

不是给人用的…

从yaml到可用的doc和api接口是挺好用的，但是写yaml本身确实挺要命，也许可以搞个转换器出来

fengb3 · 2024-08-17T12:55:57Z

显然需要能自动生成…无论是从手写本身麻烦还是存量接口角度
不是给人用的…

从yaml到可用的doc和api接口是挺好用的，但是写yaml本身确实挺要命，也许可以搞个转换器出来

各种api框架都是支持从代码 到 swagger json&yaml 再到 交互式文档 生成的. 一个可能的办法是用代码定义好端点和 实体类, 然后直接出swagger json&yaml, 并生成可部署的交互式文档出来.

相较于直接写 swagger json & yaml优点是:

代码对编写者更友好
可以分文件定义, 合并分支的时候方便

我用过比较好用的是

python的fastapi,
c#的asp.net,

都是写完代码直接跑就是api文档, 无需额外配置或生成操作, 也支持自定义css, 改文档样式.
这种方式是否可行?

z0z0r4 · 2024-08-17T14:29:54Z

...考虑下存量吧，逆天。谁这么闲去挨个糊 typing。这问题无解，成本太高

fengb3 · 2024-08-17T14:33:14Z

...考虑下存量吧，逆天。谁这么闲去挨个糊 typing。这问题无解，成本太高

如果用大语言模型基于现有的markdown去做呢？

因为我看现有的文档，虽然是按照一定格式去编写的，但是格式并没有严格到可以直接自动化读取成数据的程度。我能想到省事的重构方法就是用gpts 做一个文档阅读助手之类的东西，帮助生成代码，json什么的。（gpt前阵子出了一个json生成的功能）

亦或是对现有文档挨个检查，严格遵循某种格式。（这个工作量小一些）然后读取为元数据，再生成文档。

z0z0r4 · 2024-08-17T14:53:36Z

哪个工作量都是一坨...都得人工 review，其实没谁在乎用啥办法存接口，只是没人去标准化这坨 md 罢了...等个雅利安超人

fengb3 · 2024-08-17T15:00:01Z

彳亍口巴

Jannchie · 2024-08-18T07:46:55Z

用 openapi + LLM 是非常合理的选择。我一直在考虑使用这个方案，根据这个 repo 实现一个 fastapi 版本的符合 openapi 规范的服务器。看上去工作量并不大，但是我还有很多其他工作要处理，一直处于搁置状态（

yandujun363 · 2024-09-17T03:13:40Z

#查询进度

SocialSisterYi pinned this issue Feb 3, 2023

SocialSisterYi added the 讨论/Discussions 探讨相关内容 label Feb 3, 2023

xiaoyv404 mentioned this issue Jul 11, 2023

Support for foreign user #737

Open

SocialSisterYi mentioned this issue Sep 3, 2023

【网页版文档相关】vuepress 深色模式支持 #803

Closed

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

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

Comments

SocialSisterYi commented Feb 3, 2023 • edited Loading

原因

提议

catlair commented Feb 6, 2023

7rikka commented Feb 7, 2023

fred913 commented Feb 10, 2023

Nemo2011 commented Feb 11, 2023

MineCreeper86 commented Feb 14, 2023

SocialSisterYi commented Feb 14, 2023

MineCreeper86 commented Feb 14, 2023

MoRanYue commented Feb 16, 2023

SocialSisterYi commented Feb 20, 2023

MoRanYue commented May 21, 2023

Jannchie commented Jun 7, 2023

Drelf2018 commented Jun 10, 2023 • edited Loading

MoRanYue commented Jun 23, 2023

xiaoyv404 commented Jul 11, 2023

Drelf2018 commented Jul 11, 2023

xiaoyv404 commented Jul 11, 2023

Sualiu commented Jul 27, 2023 • edited Loading

std-microblock commented Jul 27, 2023

z-juln commented Aug 6, 2023

Sualiu commented Aug 14, 2023 • edited Loading

PetterZhukov commented Mar 10, 2024

z0z0r4 commented Mar 10, 2024

PetterZhukov commented Mar 10, 2024

z0z0r4 commented Mar 10, 2024

PetterZhukov commented Mar 10, 2024

PetterZhukov commented Mar 10, 2024

z0z0r4 commented Mar 11, 2024

Drelf2018 commented Apr 6, 2024 • edited Loading

PetterZhukov commented Apr 6, 2024

IAALAI commented Apr 24, 2024 • edited Loading

eric2788 commented Apr 29, 2024

fengb3 commented Jun 1, 2024

Genouka commented Aug 17, 2024

z0z0r4 commented Aug 17, 2024 • edited Loading

PetterZhukov commented Aug 17, 2024

fengb3 commented Aug 17, 2024 • edited Loading

z0z0r4 commented Aug 17, 2024 • edited Loading

fengb3 commented Aug 17, 2024 • edited Loading

z0z0r4 commented Aug 17, 2024 • edited Loading

fengb3 commented Aug 17, 2024

Jannchie commented Aug 18, 2024 • edited Loading

yandujun363 commented Sep 17, 2024

SocialSisterYi commented Feb 3, 2023 •

edited

Loading

Drelf2018 commented Jun 10, 2023 •

edited

Loading

Sualiu commented Jul 27, 2023 •

edited

Loading

Sualiu commented Aug 14, 2023 •

edited

Loading

Drelf2018 commented Apr 6, 2024 •

edited

Loading

IAALAI commented Apr 24, 2024 •

edited

Loading

z0z0r4 commented Aug 17, 2024 •

edited

Loading

fengb3 commented Aug 17, 2024 •

edited

Loading

z0z0r4 commented Aug 17, 2024 •

edited

Loading

fengb3 commented Aug 17, 2024 •

edited

Loading

z0z0r4 commented Aug 17, 2024 •

edited

Loading

Jannchie commented Aug 18, 2024 •

edited

Loading