简介showdoc是一款适合IT团队使用的文档工具。在阅读本文之前，您需要对showdoc有一个基本的了解。基本的介绍可以看：https://www.showdoc.cc/help对于写API文档，虽然文本编辑软件或者界面管理软件能在一定程度上提高我们的效率，但是我们还是可以尝试借助的强大功能技术，可以更自动化地生成API文档，释放自己的生产力。为此，showdoc官方提供了自动化解决方案。在代码中写入特定格式的程序注释，然后showdoc通过读取这些注释自动生成文档。由于这种方法没有和特定的语言耦合，所以可以在c++、java、php、node、python等常见的主流语言中广泛使用。这样一来，虽然可能有点繁琐当我们第一次填写注释时，它带来的后期可维护性非常高。代码改动后，不需要再次登录showdoc，直接修改代码中的注释即可。同时，也可以在持续集成或者一些自动化项目中加入自动化脚本，让“编写API文档”像“单元测试”一样纳入工程工作流程。windows下使用说明Windows不能直接运行sh脚本，需要另外下载软件。推荐下载gitforwindows：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，进入某项目的设置，点击OpenAPI查看说明。showdoc_api.sh生成的文件会放到你填写的项目中。除了api_key和api_token，还有一个url变量。如果您使用的是www.showdoc.cc，则无需修改。如果你用的是开源版的showdoc，需要把地址改成http://xx.com/server/?s=/api/open/fromComments其中，别忘了url中包含服务器目录。填写并保存。然后直接双击运行，脚本会自动递归扫描本目录及子目录下的所有文本代码文件，生成API文档。为了方便测试，官方也提供了示例。请下载：https://www.showdoc.cc/script/api_demo.test下载后将api_demo.test文件放在showdoc_api.sh所在目录或子目录下。运行时会生成文件到你指定的项目地址。如果想参考官方demo是怎么写的，可以右键api_demo.test，选择Edit。按照这种写法，在你的项目中插入类似的注释也可以达到自动生成文档的效果。详细的语法将在文章后面解释。如果想应用到其他项目，可以将showdoc_api.sh复制到其他项目中。使用方法与之前相同。Linux/Mac下使用指南首先cd进入你的项目目录，在命令行模式下输入：wgethttps://www.showdoc.cc/script/showdoc_api.sh下载后编辑vishowdoc_api.sh前面有两个脚本ofthecontent有两个变量，api_key和api_token，需要用户填写。这两个变量的取值请登录showdoc，进入某项目的设置，点击OpenAPI查看说明。showdoc_api.sh生成的文件会放到你填写的项目中。除了api_key和api_token，还有一个url变量。如果您使用的是www.showdoc.cc，则无需修改。如果你使用的是开源版的showdoc，需要将地址改为http://xx.com/server/?s=/api/...，其中，别忘了url中包含服务器目录。保存文件后。执行如下命令，脚本会自动递归扫描本目录及子目录下的所有文本代码文件，并生成API文档。chmod+xshowdoc_api.sh./showdoc_api.sh为了方便测试，官方也提供了示例。请下载：wgethttps://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*@catalogtestdocument/userrelated*@titleuserlogin*@descriptionuserlogininterface*@methodget*@urlhttps://www.showdoc.cc/home/user/login*@paramusernamerequiredstringusername*@parampasswordrequiredstringpassword*@paramnameoptionalstring用户昵称*@return{"error_code":0,"data":{"uid":"1","username":"12154545","name":"吴喜航","groupid":2,"reg_time":"1436864169","last_login_time":"0"}}*@return_paramgroupidint用户组id*@return_paramnamestring用户昵称*@remark这里是备注信息*@number99*/语法描述@catalog//生成的文档放在哪个目录下如果只是一个二级目录，直接写目录名。如果是三级目录，但是需要写二级目录/三级目录，可以用/分隔。@title//表示生成的文档标题@description//是文档内容中接口的描述信息@method//接口请求方法。一般是get或者post@url//接口URL@param//参数形式描述。一行评论对应表格的一行。用空格或制表符分隔每列信息。@return//返回内容。请在同一行压缩返回的内容。如果是json，程序会自动格式化显示。如果是非json内容，则原样显示。@return_param//返回参数的形式描述。一行评论对应表格的一行。用空格或制表符分隔每列信息。@remark//备注信息@number//可选。文档的序号。其他信息请严格按照我们的语法填写程序注释。如果格式不正确，可能会引发未知的解析错误。出于数据安全考虑，showdoc不允许直接通过代码删除文档。只能添加或修改。所以，如果要删除文档，请登录showdoc网页完成。该脚本只能通过特定的程序注释生成文档，使用范围有限。如果你想通过其他方式自由生成文档，比如通过word，通过博客软件等，请参考我们更免费开放的API：https://www.showdoc.cc/page/1...如果你的project下载太多文件可能会导致脚本扫描速度非常慢。建议将脚本放在需要生成注释的目录下。一般来说，一个项目不需要为所有目录都生成文件
