showdoc安装与脚本生成文档

2023-09-30 08:36:52

前言

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，登录后你便可以看到右上方的管理后台入口。建议登录后修改密码。
showdoc安装与脚本生成文档

脚本生成文档

初次接入脚本文档流程
1、新建一个属于自己的项目
showdoc安装与脚本生成文档

2、新建项目成功后，点击查看项目设置
showdoc安装与脚本生成文档

3、拿到参数 api_key 和 api_token，并替换 showdoc_api.sh 脚本中的参数值
showdoc安装与脚本生成文档

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))
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安装与脚本生成文档

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

showdoc安装与脚本生成文档

showdoc安装与脚本生成文档

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...，这样可以往中间任意某个位置插入自己想要的排序，不用修改其他接口的序号，避免排序混乱。
上一篇：从零开始学springboot-6.手写拦截器和自定义注解


下一篇：面试阿里4轮Java研发岗，成功拿下Offer（原题复盘）