根据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 |
用户名 |
有现成的, apiDoc: http://apidocjs.com/
@HongYangHT 你这个是大量的文本注释来支持,我个人是一直觉得这种方法不是很高。 是easyway, 不是rightway。
我一直在做一个研究,目前有点收效,通过AST直接分析出接口文档。
有兴趣的交流一下。
@HongYangHT 通过注释去维护文档费时费力,最好是能自动生成
@captainblue2013 大佬有可供参考的资料吗?拜读一下,维护文档太头大
@captainblue2013 嗯,这种方式就是比较简单,但缺点也比较明显(注释比较多)
如果是 RESTful 接口最好用 OpenAPI 格式,这样可以直接通过 swagger-ui 来展示。我们写了一个路由中间件可以自动生成 OpenAPI:https://github.com/d-band/koa-mapper
如果是普通的 JS 接口用 esdoc 就够了
@yujintang 你可以看看 https://www.npmjs.com/package/esprima 这个项目,了解一下
有的swagger 这种东西不用,非要自己造轮子哦~集成个swagger 那么容易