showdoc如何创建文件夹_如何利用showdoc自动生成API文档

介绍

showdoc是一个适合IT团队的文档工具，阅读本文前需要对showdoc有基本了解 。基本介绍可看：https://www.showdoc.cc/help

对于写API文档这件事，虽然说文本编辑软件或者接口管理软件能在某种程度上提高我们的效率，但我们依然可以试图借助技术的力量，更自动化地生成API文档，释放自己的生产力。

为此，showdoc官方提供了一种自动化解决方案。在代码里编写特定格式的程序注释，然后showdoc通过读取这些注释来自动生成文档。由于这种方式不跟特定的语言耦合，因此它的使用范围相当广泛，可用支持c++、java、php、node、python等等常见的主流语言。

采用这种方式，尽管我们在第一次填写注释的时候可能会有些繁琐，但是它后期带来的可维护性是非常高的。代码变动后，不需要再额外登录showdoc，直接在代码里修改注释即可。同时自动化的脚本也可以加入持续集成或者某些自动化工程里，让“写API文档”这件事如"单元测试"般纳入工程工作流里面。

windows下使用指引

windows无法直接运行sh脚本，需要额外下载软件。

推荐下载git for windows：https://git-scm.com/download/win 下载后直接双击安装即可。

如果从官网下载比较慢，可用考虑下载由第三方开发者维护的国内版(showdoc官方不保证其长期稳定)：

https://npm.taobao.org/mirrors/git-for-windows/v2.17.0.windows.1/Git-2.17.0-64-bit.exe

以上软件是基础环境。安装好了后，还需要下载showdoc官方脚本：https://www.showdoc.cc/script/showdoc_api.sh

下载后，将showdoc_api.sh放在你的项目目录下。右击，选择编辑。

脚本内容的前面有两个变量，api_key 和 api_token ，这个需要用户自行填写。关于这两个变量的取值，请登录showdoc，进入某个项目的设置，点击开放API，便可以看到说明。showdoc_api.sh生成的文档会放进你填写的这个项目里。除了api_key 和 api_token ，还有一个url变量。如果是使用www.showdoc.cc ，则不需要修改。如果是使用开源版showdoc，则需要将地址改为http://xx.com/server/?s=/api/open/fromComments 其中，别忘记了url里含server目录。

填写完毕，保存。然后直接双击运行，脚本会自动递归扫描本目录和子目录的所有文本代码文件，并生成API文档。

为了方便测试，官方还提供了