部署showdoc
这里直接使用docker容器启动，
docker run -d --name showdoc --user=root --privileged=true \
-p 4999:80 \
-v /data1/showdoc_data/html:/var/www/html/
star7th/showdoc
## /data1/showdoc_data/html为本地映射数据目录
创建showdoc项目
部署完成之后登录web页面
返回 选择新建的项目点击进去，这里选择通过python注释生成，点击项目设置，获取开放API设置，复制api_key,api_token
添加代码注释
官方代码注释
wget https://www.showdoc.cc/script/api_demo.test --no-check-certificate
wget https://www.showdoc.cc/script/showdoc_api.sh --no-check-certificate
# api_demo.test 官方推荐的注释案例
# showdoc_api.sh 官方自动识别注释脚本，后面会做稍微修改
备注： 下载之后把showdoc_api.sh 拷贝到要获取API文档的py文件目录下
class SecIpSearchApiHandler(BaseMisHandler):
"""
* 这是自动化生成showdoc api文档的demo
/**
* showdoc
* @catalog 测试文档/第三方API
* @title 讯飞云ip查询
* @description 提供讯飞云虚机,云物理机,虚机vip地址查询
* @method GET
* @url http://172.30.14.72:5610/api/ip
* @param ip 可选 string ip列表,以逗号分隔，不传默认返回所有
* @return {"code":0,"data":{xxxxxx}}
* @return_param business string 业务线、
* @return_param project string 子账号
* @return_param bgbu string bgbu
* @return_param owner string ip归属人
* @remark 如果是vip，返回列表可能会多个，为vip绑定的所有ip机器
* @number 99
*/
"""
@api_auth
def get(self):
xxxxxxx
#! /bin/bash
#
# 文档说明： https://www.showdoc.com.cn/page/741656402509783
#
api_key="xxxxxxxxxxxx" #api_key
api_token="xxxxxxxx" #api_token
url="http://xxxxxxx:4999/server/?s=/api/open/fromComments" #同步到的url。使用www.showdoc.com.cn的不需要修改，使用私有版的请修改
#
#
#
#
#
# 如果第一个参数是目录，则使用参数目录。若无，则使用脚本所在的目录。
if [[ -z "$1" ]] || [[ ! -d "$1" ]]; then #目录判断，如果$1不是目录或者是空，则使用当前目录
curren_dir=$(pwd)
else
curren_dir=$(
cd $1
pwd
)
fi
#echo "$curren_dir"
# 递归搜索文件
searchfile() {
old_IFS="$IFS"
IFS=$'\n' #IFS修改
for chkfile in $1/*; do
filesize=$(ls -l $chkfile | awk '{ print $5 }')
maxsize=$((1024 * 1024 * 1)) # 1M以下的文本文件才会被扫描
if [[ -f "$chkfile" ]] && [ $filesize -le $maxsize ] && [[ -n $(file $chkfile | grep text) ]]; then # 只对text文件类型操作
echo "正在扫描 $chkfile"
## 这里的匹配规则可以根据实际注释代码进行修改
result=$(sed -n -e '/"""/,/"""/p' $chkfile | grep showdoc) # 正则匹配
if [ ! -z "$result" ]; then
txt=$(sed -n -e '/"""/,/"""/p' $chkfile | grep '*')
#echo "sed -n -e '//**/,/*//p' $chkfile"
#echo $result
if [[ $txt =~ "@url" ]] && [[ $txt =~ "@title" ]]; then
echo -e "\033[32m $chkfile 扫描到内容 , 正在生成文档 \033[0m "
txt2=${txt//&/_this_and_change_}
echo $txt2
# 通过接口生成文档
curl -H 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' "${url}" --data-binary @- <<CURL_DATA
from=shell&api_key=${api_key}&api_token=${api_token}&content=${txt2}
CURL_DATA
fi
fi
fi
if [[ -d $chkfile ]]; then
searchfile $chkfile
fi
done
IFS="$old_IFS"
}
#执行搜索
searchfile $curren_dir
#
sys=$(uname)
if [[ $sys =~ "MS" ]] || [[ $sys =~ "MINGW" ]] || [[ $sys =~ "win" ]]; then
read -s -n1 -p "按任意键继续 ... " # win环境下为照顾用户习惯，停顿一下
fi
[root@salt02 handlers]# ./showdoc_api.sh
正在扫描 /opt/autobot/middleware/modules/api/handlers/core.py
/opt/autobot/middleware/modules/api/handlers/core.py 扫描到内容 , 正在生成文档
/** * showdoc * @catalog 测试文档/第三方API * @title 获取token * @description 第三方鉴权获取token * @method post * @url http://172.30.14.72:5610/api/login * @json_param {"appname":"xfyun","apikey":""} * @param appname 必选 string 用户名 * @param apikey 必选 string 密码 * @return {"code":0,"data":{"token":"xxxxx"}} * @return_param token string 获取token * @remark token有效期为1天 * @number 98 */ * 这是自动化生成showdoc api文档的demo /** * showdoc * @catalog 测试文档/第三方API * @title 讯飞云ip查询 * @description 提供讯飞云虚机,云物理机,虚机vip地址查询 * @method GET * @url http://172.30.14.72:5610/api/ip * @param ip 可选 string ip列表,以逗号分隔，不传默认返回所有 * @return {"code":0,"data":{xxxxxx}} * @return_param business string 业务线、 * @return_param project string 子账号 * @return_param bgbu string bgbu * @return_param owner string ip归属人 * @remark 如果是vip，返回列表可能会多个，为vip绑定的所有ip机器 * @number 99 */
成功
正在扫描 /opt/autobot/middleware/modules/api/handlers/showdoc_api.sh
查看页面生成的文档
