showdoc安装与脚本生成文档

前言

showdoc官方提供了一种自动化生成接口和文档的方案。在代码里编写特定格式的程序注释，然后程序就可以通过读取这些注释来自动生成文档。由于这种方式不跟特定的语言耦合，因此它的使用范围相当广泛，可以支持c++、java、php、node等等常见的主流语言。
采用这种方式，尽管我们在第一次填写注释的时候可能会有些繁琐，但是它后期带来的可维护性是非常高的。代码变动后，不需要再额外登录showdoc，直接在代码里修改注释即可。同时自动化的脚本也可以加入持续集成或者某些自动化工程里，让“写接口和文档”这件事如”单元测试”般纳入工程工作流里面。
官网文档

Docker方式安装

安装前请确保你的环境已经装好了docker服务。docker的安装教程在网上比较多，可以搜索了解下。这里重点介绍showdoc.

# 原版官方镜像安装命令(中国大陆用户不建议直接使用原版镜像，可以用后面的加速镜像)
docker pull star7th/showdoc # 中国大陆镜像安装命令（安装后记得执行docker tag命令以进行重命名）
docker pull registry.cn-shenzhen.aliyuncs.com/star7th/showdoc
docker tag registry.cn-shenzhen.aliyuncs.com/star7th/showdoc:latest star7th/showdoc:latest ##后续命令无论使用官方镜像还是加速镜像都需要执行#新建存放showdoc数据的目录
mkdir -p /showdoc_data/html
chmod  -R 777 /showdoc_data
# 如果你是想把数据挂载到其他目录，比如说/data1，那么，可以在/data1目录下新建一个showdoc_data/目录，
# 然后在根目录的新建一个软链接/showdoc_data到/data1/showdoc_data
# 这样既能保持跟官方教程推荐的路径一致，又能达到自定义存储的目的.#启动showdoc容器
docker run -d --name showdoc --user=root --privileged=true -p 4999:80 \
-v /showdoc_data/html:/var/www/html/ star7th/showdoc

根据以上命令操作的话，往后showdoc的数据都会存放在 /showdoc_data/html 目录下。
你可以打开 http://localhost:4999 来访问showdoc (localhost可改为你的服务器域名或者IP)。账户密码是showdoc/123456，登录后你便可以看到右上方的管理后台入口。建议登录后修改密码。

脚本生成文档

初次接入脚本文档流程
1、新建一个属于自己的项目

2、新建项目成功后，点击查看项目设置

3、拿到参数 api_key 和 api_token，并替换 showdoc_api.sh 脚本中的参数值

4、进入开发环境文件目录，执行 shell 脚本，生成 showdoc 接口文档，如下图：
Linux/Mac下使用指引
先cd进入你的项目目录，命令行模式下输入：

wget https://www.showdoc.cc/script/showdoc_api.sh

下载完毕，编辑showdoc_api.sh脚本
除了api_key 和 api_token ，还有一个url变量。如果是使用www.showdoc.com.cn ，则不需要修改。如果是使用私有版showdoc，则需要将地址改为http://xx.com/server/index.php?s=/api/open/fromComments ，其中，别忘记了url里含server目录。
填写完毕，保存。然后直接双击运行，脚本会自动递归扫描本目录和子目录的所有文本代码文件，并生成API文档。

vi showdoc_api.sh

示例：

#! /bin/bash
#
# 文档说明： https://www.showdoc.com.cn/page/741656402509783
#
api_key="5b9006b2326fa60cfb5028b15c130544885948135"          #api_key
api_token="a70f5ed1cdef974808caf393baa6fd9e2145029960"   #api_token
url="http://192.168.56.10:4999/server/index.php?s=/api/open/fromComments" #同步到的url。使用www.showdoc.com.cn的不需要修改，使用私有版的请修改
#
#
#
#
#
# 如果第一个参数是目录，则使用参数目录。若无，则使用脚本所在的目录。
if [[ -z "$1" ]] || [[ ! -d "$1" ]] ; then #目录判断，如果$1不是目录或者是空，则使用当前目录curren_dir=$(dirname $(readlink -f $0))
elsecurren_dir=$(cd $1; pwd)
fi
#echo "$curren_dir"
# 递归搜索文件
searchfile() {old_IFS="$IFS"IFS=$'\n'            #IFS修改for chkfile in $1/*dofilesize=`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 $resultif  [[ $txt =~ "@url" ]] && [[ $txt =~ "@title" ]]; thenecho -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_DATAfififiif [[ -d $chkfile ]] ; thensearchfile $chkfilefidoneIFS="$old_IFS"
}#执行搜索
searchfile $curren_dir#
sys=$(uname)
if [[ $sys =~ "MS"  ]] || [[ $sys =~ "MINGW"  ]] || [[ $sys =~ "win"  ]] ; then read -s -n1 -p "按任意键继续 ... " # win环境下为照顾用户习惯，停顿一下
fi

5、编写代码生成文档示例

<?php
/**
*    这是自动化生成showdoc api文档的demo
*/
class ClassName extends AnotherClass
{/*** showdoc* @catalog 测试文档/用户相关* @title 用户登录* @description 用户登录的接口* @method get* @request [{"id":"39ee5c05-f6ec-0999-2328-ac26a35e5ebd"},{"id":"39ee5c96-2a66-9b1d-4c6a-086ae5060841"}]* @url https://www.showdoc.cc/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 function showdoc(){////}

6、保存文件后。执行以下命令，脚本会自动递归扫描本目录和子目录的所有文本代码文件，并生成API文档。

chmod +x showdoc_api.sh
./showdoc_api.sh

7、showdoc 语法说明文档

/**
* showdoc
* @catalog 测试文档/用户相关
* @title 用户登录
* @description 用户登录的接口
* @method get
* @request [{"id":"39ee5c05-f6ec-0999-2328-ac26a35e5ebd"},{"id":"39ee5c96-2a66-9b1d-4c6a-086ae5060841"}]
* @url https://www.showdoc.cc/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
*/showdoc // 第一行写死就对了，标识符
@catalog // 生成文档要放到哪个目录。如果只是二级目录，则直接写目录名字。如果是三级目录，而需要写二级目录/三级目录，即用 / 隔开。
@title   // 表示生成的文档标题
@description // 是文档内容中对接口的描述信息
@method  //接口请求方式。一般是get或者post
@request // 请求示例
@url  // 接口URL
@param // 参数表格说明。一行注释对应着表格的一行。用空格或者tab符号来隔开每一列信息。
@return  // 返回内容。请把返回内容压缩在同一行内。如果是json，程序会自动进行格式化展示。 如果是非json内容，则原样展示。
@return_param // 返回参数的表格说明。一行注释对应着表格的一行。用空格或者tab符号来隔开每一列信息。
@remark  // 备注信息
@number   // 可选，文档的序号。建议以奇数排序，如：1,3,5,7...，这样可以往中间任意某个位置插入自己想要的排序，不用修改其他接口的序号，避免排序混乱。