对付写API文档这件事，虽然说文本编纂软件或者接口打点软件能在某种水平上提高我们的效率，但我们依然可以试图借助技术的力量，更自动化地生成API文档，释放本身的出产力。
为此，showdoc官方供给了一种自动化解决方案。在代码里编写特定格局的措施注释，然后showdoc通过读取这些注释来自动生成文档。由于这种方法不跟特定的语言耦合，因此它的使用范畴相当广泛，可用撑持c++、java、php、node、python等等常见的主流语言。
给与这种方法，尽管我们在第一次填写注释的时候可能会有些繁琐，但是它后期带来的可维护性长短常高的。代码改观后，不需要再特别登录showdoc，直接在代码里改削注释即可。同时自动化的脚本也可以插手连续集成或者某些自动化工程里，让“写API文档”这件事如"单元测试"般纳入工程事情流里面。
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变量。如果是使用 ，则不需要改削。如果是使用开源版showdoc，则需要将地点改为?s=http://www.mamicode.com/api/open/fromComments 此中，别忘记了url里含server目录。
填写完毕，生存。然后直接双击运行，脚本会自动递归扫描本目录和子目录的所有文本代码文件，并生成API文档。
为了便利测试，官方还供给了一个例子。请下载：
https://www.showdoc.cc/script/api_demo.test
下载后，把api_demo.test文件放在showdoc_api.sh地址的目录或者子目录下。运行的时候它便会生成文档到你指定的项目地点中。
如果你想参考官方demo是怎么写的，可用鼠标右击api_demo.test，选择编纂。模仿此种写法，，在你的项目中插入类似的注释，也能到达自动生成文档的效果。详细语法会在文章后面部辩白明。
如果你想应用到其他项目，可以把showdoc_api.sh复制一份到其他项目中。使用要领和前面一样。
Linux/Mac下使用指引先cd进入你的项目目录，命令行模式下输入：
wget https://www.showdoc.cc/script/showdoc_api.sh
下载完毕，编纂
vi showdoc_api.sh
脚本内容的前面有两个变量，api_key 和 api_token ，这个需要用户自行填写。关于这两个变量的取值，请登录showdoc，进入某个项目的设置，点击开放API，便可以看到说明。showdoc_api.sh生成的文档会放进你填写的这个项目里。除了api_key 和 api_token ，还有一个url变量。如果是使用 ，则不需要改削。如果是使用开源版showdoc，则需要将地点改为?s=http://www.mamicode.com/api/... ，此中，别忘记了url里含server目录。
生存文件后。执行以下命令，脚本会自动递归扫描本目录和子目录的所有文本代码文件，并生成API文档。
chmod +x showdoc_api.sh ./showdoc_api.sh为了便利测试，官方还供给了一个例子。请下载：
wget https://www.showdoc.cc/script/api_demo.test
下载后，把api_demo.test文件放在showdoc_api.sh地址的目录或者子目录下。运行的时候它便会生成文档到你指定的项目地点中。
如果你想参考官方demo是怎么写的，可用vi命令打开api_demo.test。模仿此种写法，在你的项目中插入类似的注释，也能到达自动生成文档的效果。详细语法会在文章后面部辩白明。
如果你还想应用到其他项目，可以把showdoc_api.sh复制一份到其他项目中。使用要领和前面一样。
或者不转移位置，直接通过参数指定扫描目录。如
./showdoc_api.sh /myapp/demo/
语法说明一个标准语法规子：
/** * showdoc * @catalog 测试文档/用户相关 * @title 用户登录 * @description 用户登录的接口 * @method get * @url https://www.showdoc.cc/home/user/login * @param username 必选 string 用户名 * @param password 必选 string 暗码 * @param name 可选 string 用户昵称 * @return {"error_code":0,"data":{"uid":"1","username":"12154545","name":"吴系挂","groupid":2,"reg_time":"1436864169","last_login_time":"0"}} * @return_param groupid int 用户组id * @return_param name string 用户昵称 * @remark 这里是备注信息 * @number 99 */