摘要：工作后一直在从事开发从以前的大包大揽到现在的退居服务端写接口当中接触过几个的接口文档管理工具或系统简单描述下功能全面而且简洁有用户权限管理功能支持支持导出有多种文档模板目录支持两级折叠功能强大权限管理邮件提醒全文搜索插件管理等重收费的一个文
工作后一直在从事PHP开发, 从以前的大包大揽到现在的退居服务端写接口, 当中接触过几个的接口文档管理工具或系统, 简单描述下:
showdoc, 功能全面而且简洁, 有用户,权限管理功能, 支持markdown, 支持导出word, 有多种文档模板, 目录支持两级折叠
confluence, 功能强大(权限管理, 邮件提醒, 全文搜索, 插件管理等), 重, 收费的一个文档管理系统
swagger, 需要在代码中写大量的注释去配合
readmine, 功能丰富类似confluence, 它的文档是以txt保存的, 可以追溯变更, 可以全文搜索, 但是写文档有点痛苦, 适合任务/bug跟踪管理等
gitbook, nodejs安装, 支持markdown, 支持npm插件, 左侧的可折叠的目录树就需要装插件, 也可以装搜索插件, 目录是多带带的markdown文件, 我使用的时候感觉从md到HTML编译太慢(600+的文档, 要编译25分钟多, 如果有增量编译或提高编译速度的插件还请各位赐教)
两个月前因为项目的原因需要一个简单的工具来管理接口文档, 这次就把开发过程中的经历记录在这里, 抛砖引玉~
主要目标:可以多人编辑
可以在浏览器中查看
有一个可以自动展开并高亮的目录
支持多级目录
支持markdown
快, 方便
解决方法:结合git就可以实现, 正好也可以利用git的权限管理功能
需要将markdown编译成HTML文件部署到内网
因为要在浏览器中查看, 这里最终选择了接入简单, 界面清爽, 无依赖的dtree.js (不依赖jQuery)
这个功能用了树的后根序遍历算法实现了对多级文件的读取(没有用递归, 担心写着写着把自己绕进去), 正好dtree.js 也支持多级目录折叠
这里我选择了segmentfault官方出的PHP编译工具类,改用 parsedown (相较sf的类他没有安全校验, 支持单行内多个换行符)
快: 编译600多个文件, PHP用时1s左右,可以接受, 而且支持增量编译; 方便: 主要体现在目录是自动生成的, 不需要多带带在编写目录
其中遇到的问题: 增量编译刚开始判断一个md文件是否需要编译成HTML, 是拿md文件的创建时间和最后修改时间做对比进行判断的,
但是后来发现, 一些复制来的, 重命名的文件用这个方法就不起作用.
最后使用了一个中间文件, 去记录本次编译的文件的时间, 再跟 max(创建时间, 最后修改时间)对比判断是否需要编译
后续使用过程中发现, 有些md文档被删除了, 但是没有自动删除最终编译后的文件,
因此, 在编译时会对md文件和最后的HTML文件求一个差集, 删掉那些多余的HTML文件
首先, dtree.js需要一定要求的json数据才能显示目录和进行展开和折叠的交互
还有, dtree.js字体比较小, 他的图片,样式,脚本文件都是相对路径, 我这里对路径做了相应修改, 使之改为基于当前域名的绝对路径, 这样部署到不同的域名下是不用修改dtree.js代码的层级目录的
组装是事先写好HTML的头部, 底部, 侧边栏等的HTML代码, 然后把这些内容与编译后的内容进行组装, 最后再放到相应的文件夹中去
美化, 这个主要是因为markdown编译工具并没有对生成的HTML元素(例如, table, code)添加样式, 我这里找了一些简洁的css样式进行了美化
这个也是耗费了我大量脑细胞写出来的, 大学的时候写动态哈夫曼编码算法的时候实现过一次树的遍历,
本以为驾轻就熟, 谁知道折腾到夜里3点多才最终写好, 这个功能也算是核心组件之一了吧
后来发现, 每次用git commit 前要先手动在命令行里编译一下(php compile.php)觉得麻烦,
就给git加了一个hook, 在提交之前自动执行编译命令, 这样就方便多了
文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。
转载请注明本文地址：https://www.ucloud.cn/yun/28204.html
摘要：总结如果你在为公司寻找一款开源免费的开发文档文档管理工具，不妨考虑一下项目，一定不会让你失望的。 Wizard 是一款开源文档管理系统，项目地址为 https://github.com/mylxsw/wizard。这个项目是 我 在2017年就开始开发的，起初只是想做一款能够在公司内部把Swagger文档管理起来的工具，但在这近两年的时间里，一直断断续续的为其添加各种功能，现在终于下决...
摘要：今天，就为开发者介绍个方便的工具。对开发者来说，是一个非常有用的工具，它提供了超过个有用的函数。该工具检查输入源代码和报告任何违反给定的标准。框架是一个开发的工具。它侧重于安全性和性能，绝对是最安全的开发框架之一。 PHP是为Web开发设计的服务器脚本语言，但也是一种通用的编程语言。超过2.4亿个索引域使用PHP，包括很多重要的网站，例如Facebook、Digg和WordPress。...
摘要：名称用途说明说明地址简单易用的请求库官网地址功能强大的请求库文档轻量级配置加载类支持多种配置格式简单的缓存类提供多种缓存驱动数字生成类似优酷视频支持多语言支持加盐生成官网地址网站地图生成器简单易用数据库操作类支持各种常见数据库文档生成 名称 用途说明 说明地址 mashape/unirest-php 简单易用的HTTP请求库 官网地址 guzzlehttp/guzzle ...
摘要：本篇文章就来分享一下两款开箱即用上手容易的图床相册程序和在线文件管理器目录列表程序，由好友开发并维护，非常适合个人站长用作图床相册和文件下载分享。虽然说现在照片还有文件存储等都可以上传到网盘中，但是国内的网盘与国外的网盘存储还有点不一样。以百度网盘与Dropbox对比为例，百度网盘顶多算是一个个人用来存放私人照片和文件的网络硬盘，如果用来分享的话很容易被百度限制或者取消下载。很多的个人站长为...
摘要：国外的话国内的国内开源的非常好用的一款文档管理系统，安装也非常方便，只需将源代码放到项目目录下自动安装运行即可，不要要注意版本必须大于界面简洁功能强大的阿里的接口管理工具，开源免费，接口自动化，数据自动生成，自动化测试，企业级管理。 在项目中，需要协同开发，所以会写许多API文档给其他同事，以前都是写一个简单的TXT文本或Word文档，口口相传，这种方式比较老土了，所以，需要有个api...
阅读 1992·2021-11-23 09:51
阅读 5272·2021-09-22 15:39
阅读 3200·2021-09-02 15:15
阅读 3351·2019-08-30 15:54
阅读 2201·2019-08-30 15:53
阅读 1265·2019-08-30 14:04
阅读 2316·2019-08-29 18:33
阅读 2194·2019-08-29 13:08
