代码注释
把接口的信息写在注释里也可以自动生成文档到showdoc,但这种我并不太喜欢,主要是侵入性比较强,让代码的阅读性变的比较差,一坨坨看着很不爽。
/**
* showdoc
* @catalog 测试文档/用户相关
* @title 用户注册
* @description 用户注册的接口
* @method post
* @url https://www.showdoc.com.cn/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
*/
public Object register(){
这种方式的实现也比较简单,还记得前边的提到的api_key、api_token这两个属性嘛,现在派上用场了,下边我用windows环境演示。
首先本地要有git环境:
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变量值,URL如果没搭建自己的文档服务不用改。
将showdoc_api.sh放在你的项目目录下,直接双击运行,脚本会自动递归扫描本目录和子目录的所有文本代码文件,并生成API文档。
showdoc_api.sh生成的文档会放进你填写api_token的这个项目里。
生成数据字典
如果我们想直接从数据库字典表生成数据字典文档,showdoc也是支持的,先下载官方提供的脚本。
wget https://www.showdoc.cc/script/showdoc_db.sh
修改脚本里的配置,数据库、api_key、api_token等信息,直接执行后数据库表结构信息同步到showdoc。
如下配置的变量名和解释
效果就是如下图这样,生成了数据表字典文档,在一些特定场景下还是很方便的。
开放API
showdoc开放了文档编辑的API,我们可以在代码中调用API创建、编辑文档。这样使用的场景就比较灵活了。
https://www.showdoc.cc/server/api/item/updateByApi
API参数如下,文档内容,可传递markdown格式的文本或者html源码都可以。
测试一下接口组装必要的参数,用简易在线API调试工具发送
{
"api_key": "8e52cbad736aa9832b92acc4b34a830e961861279",
"api_token": "9dcd8333afa7cde63bf84f8f0db5d2b2116079256",
"page_title": "xiaofu",
"page_content": "nihao"
}
看到在showdoc对应的项目里已经创建了名字为xiaofu的文档。
说两句
前边说过showdoc现有的功能postman基本都支持,但postman功能过于繁杂不够简洁,加上网络条件等诸多限制,协同办公的效率并不高,而Runapi配合showdoc在某些场景下能够很大程度上提升我们开发交付的效率,所以能自动生成的绝对不手写!
本文内容不用于商业目的,如涉及知识产权问题,请权利人联系51Testing小编(021-64471599-8017),我们将立即处理