一直想找一套开源程序来写接口文档,看过showdoc,swagger之类的,感觉都不是很方便 ,后来发现还是用markdown写技术接口文档比较方便!
写md文件推荐使用gitbook 下载地址 https://www.gitbook.com/editor/ ,通过gitbook写的文件可以单独放个目录中,目录如下
—doc
——用户中心
———-登录.md
———-注册.md
目录文件写好,如何通过url方式查看这些文档呢
这时可以引入mdjs,https://github.xuexb.com/mdjs/ 通过这个插件可以轻松的实现通过网页的模式访问这些文档
1 使用这个插件前要安装nodejs apt-get install nodejs
2 然后进入 doc目录,执行命令 npm install mdjs –save 这条命令执行前可以先执行npm init,
npm install mdjs –save执行完成后,会在当前目录下生成node_modules,这个包是运行时需要的(暂且这么说吧)
3 在有md文件的目录中加入index.js 文件的内容如下所示:
'use strict';
var Mdjs = require('mdjs');
// 实例化
var app = new Mdjs({
// 本地开发启动debug则不缓存文件
debug: true,
name:'接口文档演示',
ignore_dir: [
'.svn',
'.git',
'node_modules'
],
links: [
{
"text": "mdjs基本配置",
"url": "https://github.xuexb.com/mdjs/options.md",
},
],
});
// 清空缓存
app.clear_cache();
// 运行跑起来
app.run();
接下来是要通过nodejs来运行index.js文件 nodejs index.js,运行这个命令后可以通过
http://127.0.0.1:8091/ 直接 访问接口文档了
index.js配置信息可以访问 https://github.xuexb.com/mdjs/examples/quick.md