自动生成API文档
<p>[TOC]</p>
<h4>介绍</h4>
<p>showdoc官方提供了一种自动化生成接口和文档的方案。在代码里编写特定格式的程序注释，然后程序就可以通过读取这些注释来自动生成文档。由于这种方式不跟特定的语言耦合，因此它的使用范围相当广泛，可以支持c++、java、php、node等等常见的主流语言。</p>
<p>采用这种方式，尽管我们在第一次填写注释的时候可能会有些繁琐，但是它后期带来的可维护性是非常高的。代码变动后，不需要再额外登录showdoc，直接在代码里修改注释即可。同时自动化的脚本也可以加入持续集成或者某些自动化工程里，让“写接口和文档”这件事如"单元测试"般纳入工程工作流里面。</p>
<h4>windows下使用指引</h4>
<p>windows无法直接运行sh脚本，需要额外下载软件。</p>
<p>推荐下载git for windows：[点此下载](<a href="https://git-scm.com/download/win">https://git-scm.com/download/win</a> "点此下载") 下载后直接双击安装即可。
如果从官网下载比较慢，可用考虑下载由第三方开发者维护的国内版(showdoc官方不保证其长期稳定)：
[点此下载](<a href="https://npm.taobao.org/mirrors/git-for-windows/v2.17.0.windows.1/Git-2.17.0-64-bit.exe">https://npm.taobao.org/mirrors/git-for-windows/v2.17.0.windows.1/Git-2.17.0-64-bit.exe</a> "点此下载")</p>
<p>以上软件是基础环境。安装好了后，还需要下载showdoc官方脚本：[点此下载](<a href="https://www.showdoc.cc/script/showdoc_api.sh">https://www.showdoc.cc/script/showdoc_api.sh</a> "点此下载")
下载后，将showdoc_api.sh放在你的项目目录下。右击，选择编辑。
脚本内容的前面有两个变量，api_key 和 api_token ，这个需要用户自行填写。关于这两个变量的取值，要看你是生成showdoc项目还是runapi项目。</p>
<ul>
<li>如果你的项目是在showdoc网页上创建的，则请登录showdoc，进入某个项目的设置，点击开放API，便可以看到api_key 和 api_token的说明</li>
<li>如果你的项目是在 [runapi客户端](<a href="https://www.showdoc.com.cn/runapi/30291">https://www.showdoc.com.cn/runapi/30291</a> "runapi客户端") 上创建的，则可以点击runapi客户端右上角的菜单栏，选择“项目”。然后点击其中一个项目的“自动生成”按钮，便可以看到api_key 和 api_token的说明</li>
</ul>
<p>showdoc_api.sh生成的文档会放进api_key 所指向的这个项目里。除了api_key 和 api_token ，还有一个url变量。如果是使用www.showdoc.com.cn ，则不需要修改。如果是使用私有版showdoc，则需要将地址改为http://xx.com/server/index.php?s=/api/open/fromComments ，其中，别忘记了url里含server目录。
填写完毕，保存。然后直接双击运行，脚本会自动递归扫描本目录和子目录的所有文本代码文件，并生成API文档。
为了方便测试，官方还提供了一个例子。请下载：</p>
<p>[测试demo](<a href="https://www.showdoc.cc/script/api_demo.test">https://www.showdoc.cc/script/api_demo.test</a> "测试demo")</p>
<p>下载后，把api_demo.test文件放在showdoc_api.sh所在的目录或者子目录下。运行的时候它便会生成文档到你指定的项目地址中。
如果你想参考官方demo是怎么写的，可用鼠标右击api_demo.test，选择编辑。仿照此种写法，在你的项目中插入类似的注释，也能达到自动生成文档的效果。详细语法会在文章后面部分说明。</p>
<p>如果你想应用到其他项目，可以把showdoc_api.sh复制一份到其他项目中。使用方法和前面一样。</p>
<h4>Linux/Mac下使用指引</h4>
<p>先cd进入你的项目目录，命令行模式下输入：</p>
<p><code>wget https://www.showdoc.cc/script/showdoc_api.sh</code></p>
<p>下载完毕，编辑</p>
<p><code>vi showdoc_api.sh</code></p>
<p>脚本内容的前面有两个变量，api_key 和 api_token ，这个需要用户自行填写。关于这两个变量的取值，要看你是生成showdoc项目还是runapi项目。</p>
<ul>
<li>如果你的项目是在showdoc网页上创建的，则请登录showdoc，进入某个项目的设置，点击开放API，便可以看到api_key 和 api_token的说明</li>
<li>如果你的项目是在[ runapi客户端](<a href="https://www.showdoc.com.cn/runapi/30291">https://www.showdoc.com.cn/runapi/30291</a> " runapi客户端") 上创建的，则可以点击runapi客户端右上角的菜单栏，选择“项目”。然后点击其中一个项目的“自动生成”按钮，便可以看到api_key 和 api_token的说明</li>
</ul>
<p>showdoc_api.sh生成的文档会放进api_key 所指向的这个项目里。除了api_key 和 api_token ，还有一个url变量。如果是使用www.showdoc.com.cn ，则不需要修改。如果是使用私有版showdoc，则需要将地址改为http://xx.com/server/index.php?s=/api/open/fromComments ，其中，别忘记了url里含server目录。</p>
<p>保存文件后。执行以下命令，脚本会自动递归扫描本目录和子目录的所有文本代码文件，并生成API文档。</p>
<pre><code> chmod +x showdoc_api.sh
./showdoc_api.sh</code></pre>
<p>为了方便测试，官方还提供了一个例子。请下载：
<code>wget https://www.showdoc.cc/script/api_demo.test</code></p>
<p>下载后，把api_demo.test文件放在showdoc_api.sh所在的目录或者子目录下。运行的时候它便会生成文档到你指定的项目地址中。
如果你想参考官方demo是怎么写的，可用vi命令打开api_demo.test。仿照此种写法，在你的项目中插入类似的注释，也能达到自动生成文档的效果。详细语法会在文章后面部分说明。</p>
<p>如果你还想应用到其他项目，可以把showdoc_api.sh复制一份到其他项目中。使用方法和前面一样。
或者不转移位置，直接通过参数指定扫描目录。如</p>
<p><code>./showdoc_api.sh /myapp/demo/</code></p>
<h4>语法说明</h4>
<p>一个标准语法例子：</p>
<pre><code> /**
* showdoc
* @catalog 测试文档/用户相关
* @title 用户登录
* @description 用户登录的接口
* @method get
* @url https://www.showdoc.cc/home/user/login
* @header token 可选 string 设备token
* @param username 必选 string 用户名
* @param password 必选 string 密码
* @param name 可选 string 用户昵称
* @return {&quot;error_code&quot;:0,&quot;data&quot;:{&quot;uid&quot;:&quot;1&quot;,&quot;username&quot;:&quot;12154545&quot;,&quot;name&quot;:&quot;吴系挂&quot;,&quot;groupid&quot;:2,&quot;reg_time&quot;:&quot;1436864169&quot;,&quot;last_login_time&quot;:&quot;0&quot;}}
* @return_param groupid int 用户组id
* @return_param name string 用户昵称
* @remark 这里是备注信息
* @number 99
*/
</code></pre>
<table>
<thead>
<tr>
<th>关键字</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>@catalog</code></td>
<td>生成文档要放到哪个目录。如果只是二级目录，则直接写目录名字。如果是三级目录，而需要写二级目录/三级目录，即用<code>/</code>隔开。如"一层/二层/三层"</td>
</tr>
<tr>
<td><code>@title</code></td>
<td>表示生成的文档标题</td>
</tr>
<tr>
<td><code>@description</code></td>
<td>是文档内容中对接口的描述信息</td>
</tr>
<tr>
<td><code>@method</code></td>
<td>接口请求方式。一般是get或者post</td>
</tr>
<tr>
<td><code>@url</code></td>
<td>接口URL。不要在URL中使用&符号来传递参数。传递参数请写在参数表格中</td>
</tr>
<tr>
<td><code>@header</code></td>
<td>可选。header说明。一行注释对应着表格的一行。用空格或者tab符号来隔开每一列信息。</td>
</tr>
<tr>
<td><code>@param</code></td>
<td>参数表格说明。一行注释对应着表格的一行。用空格或者tab符号来隔开每一列信息。</td>
</tr>
<tr>
<td><code>@json_param</code></td>
<td>可选。当请求参数是json的时候，可增加此标签。请把json内容压缩在同一行内。当采用这种json方式的时候，上面的@param表格的参数说明将自动变成是对此json的字段描述说明</td>
</tr>
<tr>
<td><code>@return</code></td>
<td>返回内容。请把返回内容压缩在同一行内。如果是json，程序会自动进行格式化展示。 如果是非json内容，则原样展示。</td>
</tr>
<tr>
<td><code>@return_param</code></td>
<td>返回参数的表格说明。一行注释对应着表格的一行。用空格或者tab符号来隔开每一列信息。</td>
</tr>
<tr>
<td><code>@remark</code></td>
<td>备注信息</td>
</tr>
<tr>
<td><code>@number</code></td>
<td>可选。文档的序号。</td>
</tr>
</tbody>
</table>
<h4>其他信息</h4>
<p>请严格按照我们的语法来填写程序注释。如果格式不对，则可能引发未知的解析错误。</p>
<p>出于数据安全考虑，showdoc不允许直接通过代码删除文档。只能新增或者修改。所以，如果你要删除文档，请登录showdoc网页端（如果是runapi项目则需要登录runapi客户端）完成。</p>
<p>本脚本只能通过特定的程序注释来生成文档，使用范围有限。如果你是想通过其他方式自由地生成文档，如通过word、通过博客软件等，请参考我们更自由的开放API：[点击跳转](<a href="https://www.showdoc.cc/page/102098">https://www.showdoc.cc/page/102098</a> "点击跳转")</p>
<p>如果你的项目下太多文件，则可能导致脚本扫描很慢。推荐把脚本放到需要生成注释的那个目录里。一般来讲，一个项目不会所有目录都需要生成文档的</p>