Markdown-拓展 Docsify 构建接口文档

发表于 更新于 分类于 ，

优点：使用 markdown 编写，docsify 作为支撑。快速高效，若搭载搜索功能，功能较为完善。且可部署在内网环境。

缺点：不支持直接点击按钮进行 HTTP 请求，需要手动粘贴参数到 POSTMAN 等工具。

Docsify 初始化 & 运行

1
2
docsify init ./docs
docsify run ./docs

开启搜索功能

此时必须开启多页文档才行。详见 https://docsify.js.org/#/zh-cn/more-pages

1
2
3
└── docs
    ├── README.md
    ├── guide.md

开启字数统计功能
add js

1
<script src="//unpkg.com/docsify-count/dist/countable.js"></script>

增加配置

1
2
3
4
5
6
7
8
window.$docsify = {
  count:{
    countable:true,
    fontsize:'0.9em',
    color:'rgb(90,90,90)',
    language:'chinese'
  }
}

开启复制到剪切板功能

1
<script src="//cdn.jsdelivr.net/npm/docsify-copy-code"></script>

增加配置

1
2
3
4
5
copyCode: {
 buttonText: {'/' : '点击复制'},
 errorText: {'/' : '错误'},
 successText: {'/' : '已复制'}
}

开启代码高亮功能
docsify内置的代码高亮工具是 Prism。Prism 默认支持的语言如下：

  • Markup - markup, html, xml, svg, mathml, ssml, atom, rss
  • CSS - css
  • C-like - clike
  • JavaScript - javascript, js

添加额外的语法支持需要通过CDN添加相应的语法文件 :

1
2
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-php.min.js"></script>

要使用语法高亮，需要在代码块第一行添加对应的语言声明，示例如下:

1
2
<p>This is a paragraph</p>
<a href="//docsify.js.org/">Docsify</a>

prism-properties.min.js
prism-java.min.js
prism-yaml.min.js
prism-sql.min.js

最终成品

_sidebar.md

1
2
* [xxx-app端](/)
* [xxx-微信端](/wechat)

index.html

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
<!DOCTYPE html>
<html lang="zh">

<head>
    <meta charset="UTF-8">
    <title>接口文档</title>
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
    <meta name="description" content="Description">
    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
    <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css" title="vue">
    <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/dark.css" title="dark" disabled>
    <link rel="stylesheet" href="css/theme-simple-dark.css" disabled>

    <style>
    </style>
</head>

<body>
    <div id="app">加载中...</div>
    <script>
        window.$docsify = {
            auto2top: true,
            loadSidebar: true,
            maxLevel: 2,
            subMaxLevel: 2,
            name: '',
            search: {
              maxAge: 600000,// 过期时间，设置为10分钟
              noData: {
                '/': '没有结果!'
              },
              paths: 'auto',
              placeholder: {
                '/': '搜索接口'
              },
              // 搜索标题的最大层级, 1 - 6
              depth: 2,
            },

             count: {
                countable:true,
                fontsize:'0.9em',
                color:'rgb(90,90,90)',
                language:'chinese',
                isExpected: false // 是否显示需要阅读的分钟数

             },

            copyCode: {
              buttonText: {'/' : '点击复制'},
              errorText: {'/' : '错误'},
              successText: {'/' : '已复制'}
            },

            plugins: [
                function (hook, vm) {

                var footer = [
                    '<hr/>',
                    '<footer>',
                    '<span>likai&copy;2020.</span>',
                    '<span> Proudly published with <a href="https://github.com/docsifyjs/docsify" target="_blank">docsify</a></span>',
                    ' V' + window.Docsify.version,
                    '</footer>'
                  ].join('');

                  hook.afterEach(function(html) {
                    return html + footer;
                  });
                }
            ],

        }
  </script>
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
  <script src="//unpkg.com/docsify-count/dist/countable.js"></script>
  <script src="//cdn.jsdelivr.net/npm/docsify-copy-code"></script>
</body>

</html>

成品效果

顶部展示效果

尾部展示效果

总结

接口文档采用 markdown 编写，入门较容易

附录一个实用接口文档的 markdown 模板 - 简书
https://www.jianshu.com/p/f5a0b5894ffc