showdoc自动化生成接口和文档的方案

介绍

showdoc开放文档编辑的API，供使用者更加方便地操作文档数据。利用开放API，你可以自动化地完成很多事。例如下面列举三个典型的应用场景：

• 假如你的团队有很多现成的文档资料，但这些文档资料大多以word的形式存在。如果人工复制粘粘，工作量会有点多。此时你可以写一个自动脚本，从文件中生成文档，然后通过showdoc的开放api批量地把文档更新进去。

• 你是个后端程序员，你想在写完代码后，文档能自动更新到showdoc。为了实现这个效果，你可以写一个脚本程序，根据你项目代码的结构，自动生成文档数据，然后通过showdoc的开放api自动更新。

• 你有很多笔记教程，存在笔记软件或者网站博客中，但你想把它们归类在一起供人们查阅。 这时你可以写程序批量导入showdoc

windows下使用指引

在需要生成的地方放入以下文件，创建文件build_doc.sh，并填入以下内容

#! /bin/bash
#
# 文档说明： https://www.showdoc.com.cn/page/741656402509783 
# 
api_key="9b9a7xxxxxxxxxx336"             #api_key
api_token="c1fbxxxxxxxxxx2403"     #api_token
url="http://域名.com/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)
                    #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_}
                        # 通过接口生成文档
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

接口添加特定备注

/**
* showdoc
* @cover 0
* @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 {"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
*/