joi2md
发布于 5 年前 作者 yujintang 4273 次浏览 来自 分享

根据Joi 参数判断,去实现文档的request部分,但是总感觉文档用起来还是不是太顺手,求star与提建议。

地址:https://github.com/ufo-parts/joi2md Example

const Joi = require('joi');
const Joi2md = require('joi2md');

const Jm = new Joi2md();
// 设置schema
Jm.setSchema({
    name: Joi.number().default(1).required().notes('用户名'),
})
// schema 转换为行数据
Jm.transferRows()
// 得到markdown字符串
Jm.setPrintHeaders([
    ['path', '参数名'],
    ['type', '类型'],
    ['presence', '必填'],
    ['default', '默认值'],
    ['notes', '说明'],
  ]);
const result = Jm.printMd()
console.log(result)

Result

参数名 类型 必填 默认值 说明
name number true 1 用户名
9 回复

@HongYangHT 你这个是大量的文本注释来支持,我个人是一直觉得这种方法不是很高。 是easyway, 不是rightway。

我一直在做一个研究,目前有点收效,通过AST直接分析出接口文档。

有兴趣的交流一下。

@HongYangHT 通过注释去维护文档费时费力,最好是能自动生成

@captainblue2013 大佬有可供参考的资料吗?拜读一下,维护文档太头大

@captainblue2013 嗯,这种方式就是比较简单,但缺点也比较明显(注释比较多)

如果是 RESTful 接口最好用 OpenAPI 格式,这样可以直接通过 swagger-ui 来展示。我们写了一个路由中间件可以自动生成 OpenAPI:https://github.com/d-band/koa-mapper

如果是普通的 JS 接口用 esdoc 就够了

有的swagger 这种东西不用,非要自己造轮子哦~集成个swagger 那么容易

回到顶部