用markdown编辑器写技术接口文档

一直想找一套开源程序来写接口文档,看过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