Markdown 拓展-Docsify 构建接口文档

2022-05-17 14:09:38 浏览数 (1)

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

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

Docsify 初始化 & 运行

代码语言：javascript复制
docsify init ./docs
docsify run ./docs

开启搜索功能

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

代码语言：javascript复制
└── docs
    ├── README.md
    ├── guide.md

开启字数统计功能

add js

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

增加配置

代码语言：javascript复制
window.$docsify = {
  count:{
    countable:true,
    fontsize:'0.9em',
    color:'rgb(90,90,90)',
    language:'chinese'
  }
}

开启复制到剪切板功能

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

增加配置

代码语言：javascript复制
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添加相应的语法文件 :

代码语言：javascript复制
<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>

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

代码语言：javascript复制
    <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

代码语言：javascript复制
* [xxx-app端](/)
* [xxx-微信端](/wechat)

index.html

代码语言：javascript复制
<!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://cloud.tencent.com/developer/article/2005483

markdown javascript https java 网络安全

0 人点赞