DokuWiki的发现之旅

★DokuWiki介绍

       Wiki是什么？是一种允许一群用户用简单的描述来创建和连接一组网页的社会计算系统，可以让人们在web的基础上对Wiki文本进行浏览、创建和更改，是一种人类的知识的网络系统，有助于在一个社群内共享某个领域的知识。

       DokuWiki是什么？是一个符合标准、简单易用的Wiki，主要用于创建任何类型的文件。它适用于开发团体、工作小组和小型企业。它有简单而强大的语法，确保数据文件在Wiki外仍然可以阅读，并简化了结构化文本的创建。所有数据都保存在纯文本文件中--不需要数据库。

★DokuWiki相遇

       事情是这个样子的：之前公司的主要产品是一款APP，首先我们需要定义接口文档，方便前后端同时开发。刚开始使用传统的方式--万能的Word+SVN，SVN主要用于文档的版本控制和协作。刚开始接口少，更新完文档之后，吼一嗓子，同事就会同步最新的文档，貌似还很顺利。随着接口越来越多，修改越来越频繁，这种靠吼的同步方式，就显得效率低下。同时也暴露了一些弊端，虽然有版本控制，会存储历史记录，但是SVN对这种非简单格式的文本不能记录文档的具体变化，也就不能对比历史记录修改了什么，当对接口历史追溯的时候，就显得捉襟见肘，这就造成沟通和维护成本比较高。这时就亟待一个接口文档的管理系统解决以上问题。

       首先第一个要求必须是Web应用，这样客户端只需要浏览器，可以方便在线修改后及时同步更新。其次是可以部署到本地的，最好是开源，我们的接口文档属于内部人员查看，不能暴露给第三方，虽然某些系统可以提供在线服务，但是安全性得不到保证。还有比较重要的一点就是，上手容易，门槛较低，最好有统一的接口模板，不用每次重新写，开发人员写代码已属不易，何必跟自己过不去呢。于是在网上一番搜索，总结了现在市面上比较流行的接口管理或者文档管理系统，由于时间和水平有限，覆盖面可能只有一小部分，只针对某类比较典型的框架或系统进行分析，仅代表个人观点。

       1、Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger文档的编写可以采用两种方式，一是手动编写Swagger文档，大概看了一下swagger的语法，还挺复杂的，暂且不讨论。二是可以从代码注释中自动生成，这也是目前公司所采用的，这种方式语法简洁，使用方便，一键生成固定的文档格式，还可以在线调试接口，确实是开发利器。但是这种方式做为一种文档管理系统还是有一些局限性。例如不能查看接口的文档修改历史，只能通过代码中的注释和版本管理工具进行对比，还有就是没有搜索的功能，所以我们现在是使用swagger作为辅助文档和在线调试的工具。

       2、ShowDoc一个适合IT团队的在线文档分享工具，使用Markdown编辑实时预览，也可以编辑模板一键插入，有历史版本可以追溯，使用简单，功能专注，还有word文档导出功能，确实作为一个接口文档管理系统功能已经够用了，个人来说比较喜欢。但是考虑到公司以后的发展，需要在线存储文件，更精细化的权限控制等功能，这些ShowDoc暂时无法实现，只能忍痛割爱了。同类型的产品还有MinDoc、小幺鸡等，做的都还可以，可以试用对比一下。

       3、RAP是一个阿里巴巴旗下的阿里妈妈前端团队出品的mock工具，这类工具主要通过接口定义，自动生成模拟数据，前端不再依赖于后端开发进度可以独立开发，并且可以生成复杂边界数据，实现自动化测试，多人在线编辑提高协作效率。同类工具还有YApi和EasyMock，EasyMock是同事极力推荐的，可以结合swagger模拟生成数据，这点确实很方便，还有其他一些比较适用的功能，以后有机会可以试用一下。这类工具确实很方便，但是不太满足现阶段公司的文档需求，以后可以根据业务发展选用该类工具。

      4、Confluence被认为是最好用的企业级Wiki和知识管理工具，大型企业用的比较多，功能很强大。在他们官网上体验了一把，由于国外速度比较慢，很多功能没有试用，不做评价。查了下相关资料，配置麻烦，而且还是收费的……虽说可以破解，但是也懒得折腾了。

       5、DokuWiki是什么上面都已经介绍过了，为什么最终会选用它呢？首先是不需要数据库这点吸引我在服务器上部署一套试用，因为公司的服务器资源有限，上面跑的还有正式应用……不敢瞎折腾，所以要尽量少的影响正式环境。刚开始使用，第一感觉就是丑、功能少、配置麻烦，但是想想好不容易（装了个PHP环境~）部署到服务器上不能轻易放弃啊，就在网上搜各种教程。发现了复旦大学物理教学实验中心的网站，该网站就是使用DokuWiki搭建的，虽然页面复古了些，但是作为一个实验室内信息共享的平台已经很完善了，里面也有一些DokuWiki的入门文章，从而认识到Wiki这种分享信息的形式发展潜力，wiki是任何人都可以编辑的网页，然后以超链接的形式将信息联系起来，构建一个有灵魂的知识网络系统，坚定了自己使用DokuWiki的信心。从这之后就开始了DokuWiki的折腾之旅，中间也是遇到了各种问题，入门和使用起来也不是很方便，但是通过各种插件也可以满足大多数功能，下一篇就谈一下自己是怎样使用的。