markdown 转 word 工具推荐，API文档、数据库文档快速生成调研

最近工作中做了一些调研性的工作，好久没更新博客了，今天就水一篇把，最近在补项目中的相关文档，众所周知接口文档和数据库字段文档是必须的，针对这两块东西如果是微服务的话接口众多，要从零开始梳理不知道要到猴年马月，所以力求花最少时间搞定这两样东西。

为什么标题要拧出来说 markdown 这个东西，因为现在写的大多数文档都是以 .md 格式写的，习惯了真的就是比 word 这些工具好用啊，不知道为什么 wps 这个东西现在特别的臃肿，每次打开都感觉特别卡。

接口 API 导出调研

主要调研了 apifox、apipost、swagger 解析导出、knife4j 导出方案。

要想导出非常完美的文档要依赖平时代码中的 javadoc 注释或者 swagger 注解打得好。但是大家懂的，要求每个人都去完善注释不大现实。

API 文档嘛，主要是客户需要肯定就要 word，但是理论来说交付完毕给 pdf 也是 ok 的，以前还拿到过对接文档是直接把 swagger 导出成 html，只要能看能解决问题就 ok 嘛，但是为了方便二次修改所以最终还是导出 word，如果要 pdf 再转一次就行了。

所有方案都是围绕 swagger 自带的接口生成，无非就是解析然后生成不同的格式。

apifox 和 apipost 同属于一类，导出的时候都不能直接导出 word，只能先导出 markdown，然后再使用类似于 pandoc 这种工具进行转换成其他格式。

swagger 解析导出就还得去定义 word 模板渲染啥的，虽然找了有类似于这样的开源项目，但是如果注释不是很完善很容易各种报错。

最终选择了 knife4j 直接在线导出 markdown文件。

很多人会问，离线文档不是有下载 word 吗，你猜我为什么不用？哈哈哈哈，这上面的 word 其实不是 word，而是转成 html 然后整到一个 word 文档里，特别奇怪，还不方便看。

然后将 md 转成 word 即可，也是找了一堆，不是样式有问题就是格式错乱，特别是表格很容易出问题，最终选定了markdocx 这个开源工具实现，能达到效果。

markdocx 项目介绍

markdocx 是一个开源项目，可以将你的 markdown 文件转换为 MS Word（.docx）/ Convert your Markdown files to MS Word (.docx)。

项目地址：https://github.com/ccwud/markdocx

windows 下可以直接下载 release 包使用，macos 的话可以直接安装 python 源码运行食用。

markdocx.exe C:\Users\admin\Downloads\md\input -o C:\Users\admin\Downloads\md\word-output -s C:\Users\admin\Downloads\md\style.yaml

数据库文档生成调研

数据库文档因为项目有使用 mySQL（MariaDB） 和 达梦数据库，所以必须至少要支持这 2 种数据库的自动文档生成。

尝试过：DBCHM、SmartSQL、screw。

前两个工具每次导出都有奇奇怪怪的问题，不知道是不是因为公司电脑是 windows11，还以为是我操作不对，看也是很久没有维护了，所以没折腾。

screw这个工具官方仓库不支持达梦数据库，但是看到有 fork 项目添加支持了达梦数据库，然后也可以自定义导出样式和模板。

所以直接最终选用了screw，支持达梦数据库的点这个仓库。

直接看效果：

screw 项目介绍

screw 是一个开源项目，专注于简洁好用的数据库表结构文档生成工具。虽然官方仓库好久没有更新了，如果不支持你所使用的数据库，可以自己 fork 代码进行二开，主要就是实现一下查询数据库的元数据信息就行了。实现逻辑参考：#screw-core/src/main/java/cn/smallbun/screw/core/query

项目开源地址：https://github.com/pig-mesh/screw

写在最后

通过本文你可以快速了解到生成项目 API 接口、数据库字典文档，大大减少人力成本。最后想说的确实开源项目降低了技术的门槛，让人人都能享受到开源的乐趣。但是开源项目大多数是用爱发电，大多数公司可能也不会意思把“烂代码”暴露给大众看，但是长远看，开源一些公共的项目更加有利于提升企业产品的知名度和商业化方案的推广，最后的最后，如果大家有更和的解决方案可以评论区留言大家一起探讨。