Smart

Smart-doc优点：

        无侵入的接口文档、在线文档生成器。三种生成文档方式。对于程序代码开发中只需要加注释（符合一定的语法，五分钟可掌握）就能生成在线文档。可以支持c++、java、php、node等等常见的主流语言。

Smart-doc缺点：

        注重文档内容，不提供测试、mock等功能，如果要使用测试mock等功能需要先用RunApi工具手动维护接口内容，而大部分比如postman、apifox等项目管理工具都是支持直接导入swagger文档自动生成的。而且swagger本身也提供了一定的接口测试功能，如果有测试的需要的话swagger可能是更好的选择。

 如何使用：

        ShowDoc，该连接指向官方文档阐述，字太多，觉得我阐述的不好的可以看官方的。以下我精简归纳一下

使用脚本实现：

  前提环境：windows系统、git（下载git for windows：Git - Downloading Package）、shell脚本（.sh）

怎么写注释：（idea新建Live Template就能一劳永逸了）

//注释示例/*** showdoc* @catalog 测试文档/用户相关* @title 用户登录2* @description 用户登录的接口（参数以纯json的方式提交）* @method post* @url * @json_param {"username":"test","password":"***"} * @param username 必选 string 用户名  * @param password 必选 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*/public function login2(){}

怎么生成在线文档：

1.    showdoc_api.sh放在需要生成文档的代码目录下，脚本会遍历子目录的。（我是把要生成的文档的文件放到一个指定目录里面，这样很节省脚本执行时间）
2. 编辑showdoc_api.sh，替换成自己的api_key 和 api_token，公共版的url不用动，保存       
3.   获取api_key 和 api_token（生成对应的项目目录，每个项目都又子集的key和token）  
   1. 如果你的项目是在showdoc网页上创建的，则请登录showdoc，进入某个项目的设置，点击开放API，便可以看到api_key 和 api_token的说明
   2. 如果你的项目是在runapi客户端（ ShowDoc ） 上创建的，则可以点击runapi客户端最左侧的菜单栏，选择“项目”。然后点击其中一个项目的“自动生成”按钮，便可以看到api_key 和 api_token的说明
4. 双击 运行showdoc_api.sh脚本，生成在线文档了，去自己的smart-doc账户上看看吧 。                           

Smart

Smart-doc优点：

        无侵入的接口文档、在线文档生成器。三种生成文档方式。对于程序代码开发中只需要加注释（符合一定的语法，五分钟可掌握）就能生成在线文档。可以支持c++、java、php、node等等常见的主流语言。

Smart-doc缺点：

        注重文档内容，不提供测试、mock等功能，如果要使用测试mock等功能需要先用RunApi工具手动维护接口内容，而大部分比如postman、apifox等项目管理工具都是支持直接导入swagger文档自动生成的。而且swagger本身也提供了一定的接口测试功能，如果有测试的需要的话swagger可能是更好的选择。

 如何使用：

        ShowDoc，该连接指向官方文档阐述，字太多，觉得我阐述的不好的可以看官方的。以下我精简归纳一下

使用脚本实现：

  前提环境：windows系统、git（下载git for windows：Git - Downloading Package）、shell脚本（.sh）

怎么写注释：（idea新建Live Template就能一劳永逸了）

//注释示例/*** showdoc* @catalog 测试文档/用户相关* @title 用户登录2* @description 用户登录的接口（参数以纯json的方式提交）* @method post* @url * @json_param {"username":"test","password":"***"} * @param username 必选 string 用户名  * @param password 必选 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*/public function login2(){}

怎么生成在线文档：

1.    showdoc_api.sh放在需要生成文档的代码目录下，脚本会遍历子目录的。（我是把要生成的文档的文件放到一个指定目录里面，这样很节省脚本执行时间）
2. 编辑showdoc_api.sh，替换成自己的api_key 和 api_token，公共版的url不用动，保存       
3.   获取api_key 和 api_token（生成对应的项目目录，每个项目都又子集的key和token）  
   1. 如果你的项目是在showdoc网页上创建的，则请登录showdoc，进入某个项目的设置，点击开放API，便可以看到api_key 和 api_token的说明
   2. 如果你的项目是在runapi客户端（ ShowDoc ） 上创建的，则可以点击runapi客户端最左侧的菜单栏，选择“项目”。然后点击其中一个项目的“自动生成”按钮，便可以看到api_key 和 api_token的说明
4. 双击 运行showdoc_api.sh脚本，生成在线文档了，去自己的smart-doc账户上看看吧 。