Loading... ## 写在开始   过去两年,我从0开始搭建IOMS,目前为止也有了一些功能,期间我深切的体会到一个问题:写代码可以,写文档不行,写文档真是要了人的老命!但当我在看另外一个项目的时候,我又会发出:为什么没有文档?/为什么文档写的这么烂!的感慨,这何尝不是一种又当又立呢?既不想写文档,又想别人把文档写好,这是极其矛盾的行为。同时,随着IOMS开发担子的转移,新的开发人员对此也是深恶痛绝,为什么IOMS没有一个好的文档?这叫我怎么开发?这垃圾系统狗都不用啊!同时也越来越多的同志来问我问题,一个一个教确实会有点疲乏。   基于此,我汗流浃背,使命感油然而生,为了不背负一世骂名,我决定写一份文档...写文档肯定分为两部分,第一部分是写在哪里,第二部分是怎么写。经过我的调研发现,ShowDoc是一个很不错的工具,甚至可以自部署,而且ShowDoc也提供了自动生成Api文档的方式,嗯,很符合我的定位,干!说干就干,第一步就是部署ShowDoc。 ## ShowDoc的自部署   废话不多说,ShowDoc是可以使用docker部署的,自然也可以使用docker-compose来组织镜像、部署,在此只提供docker-compose.yml文件,镜像什么拉不下来,还是得另外想想办法呐! version: '3.3' services: showdoc: container_name: showdoc privileged: true ports: - '39410:80' volumes: - './data:/var/www/html/' image: showdoc:latest ## 利用ShowDoc自动生成SpringBoot工程的Api接口文档   接口文档当然可以手写,不过那样会写的人仰马翻。除了手动编辑文档外,ShowDoc的官方提供了三种自动生成接口文档的方法: * [X] 使用RunApi工具自动生成:https://www.showdoc.com.cn/runapi * [X] 使用程序注释自动生成:https://www.showdoc.com.cn/page/741656402509783 * [X] 自己写程序调用接口来生成:https://www.showdoc.com.cn/page/102098   虽然官方推荐“使用RunApi工具自动生成”这种方式,但我秉持着怎么来怎么方便的态度,同时接口也已经开发了非常多了,RunApi工具似乎已经不适合了(我也不知道适不适合,我自己说服自己),我采用了第二种方式自动生成Api。 ### 自动生成脚本   第一步,就是在SpringBoot的Controller目录下放一个从官方下载来的脚本:showdoc_api.sh,这个脚本会自动扫描当前目录与子目录下的所有接口,提取接口前的注释信息生成Api文档,我们需要根据要求修改api_key、api_token与url 脚本的内容如下(我被url给折磨了很久,可以按照我提供的这个url进行改动): #! /bin/bash # # 文档说明: https://www.showdoc.com.cn/page/741656402509783 # api_key="XXXXXXXXXXXXXXXX" #api_key api_token="XXXXXXXXXXXXXXX" #api_token url="https://showdoc.maisblog.cn/server/?s=/api/open/fromComments" #同步到的url。将域名改为自己部署的域名 # # 如果第一个参数是目录,则使用参数目录。若无,则使用脚本所在的目录。 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 ### SpringBoot接口注释   第二步,就是在SpringBoot的Controller目录下的接口文件中的每一个接口添加注释,以登录接口举例: /** * showdoc * @catalog 接口文档/用户 * @title 用户登录 * @description 用户登录的接口。 * @method post * @url /user/login * @param username 必选 string 用户名 * @param password 必选 string 密码 * @param captcha 必选 string 验证码 * @json_param {"username":"admin","password":"admin","captcha":"doge"} * @return {"data": {"roleId": [1,4],"secret": "1c0212b0f75f814d85b0196d050429a7","token": "XXX.XXX.XXX"},"code": 20001,"message": "登录成功!上次登陆时间:2024-10-10 16:14:33"} * @return_param roleId List<Integer> 用户身份列表 * @return_param secret string 单点登录凭证 * @return_param token string 登录凭证 * @return_param code string 响应码 * @return_param message string 响应消息 * @remark 用户登录的接口 * @number 1 */ 注释的每一项的含义如下: <table style="text-align:left"> <thead> <tr> <th>关键字</th> <th>说明</th> </tr> </thead> <tbody> <tr style="background-color: rgb(255, 255, 255);"> <td><code>@catalog</code></td> <td>生成文档要放到哪个目录。如果只是二级目录,则直接写目录名字。如果是三级目录,而需要写二级目录/三级目录,即用<code>/</code>隔开。如”一层/二层/三层”</td> </tr> <tr style="background-color: rgb(255, 255, 255);"> <td><code>@title</code></td> <td>表示生成的文档标题</td> </tr> <tr style="background-color: rgb(255, 255, 255);"> <td><code>@description</code></td> <td>是文档内容中对接口的描述信息</td> </tr> <tr style="background-color: rgb(255, 255, 255);"> <td><code>@method</code></td> <td>接口请求方式。一般是get或者post</td> </tr> <tr style="background-color: rgb(255, 255, 255);"> <td><code>@url</code></td> <td>接口URL。不要在URL中使用&符号来传递参数。传递参数请写在参数表格中</td> </tr> <tr style="background-color: rgb(255, 255, 255);"> <td><code>@header</code></td> <td>可选。header说明。一行注释对应着表格的一行。用空格或者tab符号来隔开每一列信息。</td> </tr> <tr style="background-color: rgb(255, 255, 255);"> <td><code>@param</code></td> <td>参数表格说明。一行注释对应着表格的一行。用空格或者tab符号来隔开每一列信息。</td> </tr> <tr style="background-color: rgb(255, 255, 255);"> <td><code>@json_param</code></td> <td>可选。当请求参数是json的时候,可增加此标签。请把json内容压缩在同一行内。当采用这种json方式的时候,上面的@param表格的参数说明将自动变成是对此json的字段描述说明</td> </tr> <tr style="background-color: rgb(255, 255, 255);"> <td><code>@return</code></td> <td>返回内容。请把返回内容压缩在同一行内。如果是json,程序会自动进行格式化展示。 如果是非json内容,则原样展示。</td> </tr> <tr style="background-color: rgb(255, 255, 255);"> <td><code>@return_param</code></td> <td>返回参数的表格说明。一行注释对应着表格的一行。用空格或者tab符号来隔开每一列信息。</td> </tr> <tr style="background-color: rgb(255, 255, 255);"> <td><code>@remark</code></td> <td>备注信息</td> </tr> <tr style="background-color: rgb(255, 255, 255);"> <td><code>@number</code></td> <td>可选。文档的序号。</td> </tr> </tbody> </table> ### 运行showdoc_api.sh   Windows无法直接运行sh脚本,需要额外下载软件。你如果安装了Git,那么使用Git Bash可以直接自动运行,运行后会扫描你的Controller文件夹,自动生成文档,运行后如果你看到以下提示,说明已经成功啦! ![运行成功提示][1]   登录自部署的ShowDoc,就会发现,Api文档已经全部生成上去了。 ![自动生成的Api文档][2] ## 写在结尾   这篇博客拖了十天左右,老早就想写,计划里好多天都有写这个任务,今天终于写完了,写完之后我发现,官方似乎有一个比我介绍的[更详细的文档][3],汗颜了...   另外,IOMS的手册在https://showdoc.maisblog.cn/web/#/694756495,接口文档还没写完,也在慢慢的完善,听闻最近谷本锐师弟在写一点心得,估摸着也可以放进这个文档里,IOMS系统的开发人员请参考。 [1]: https://www.maisblog.cn/usr/uploads/2024/10/3329050790.png [2]: https://www.maisblog.cn/usr/uploads/2024/10/4230480706.png [3]: https://www.showdoc.com.cn/page/741656402509783 最后修改:2024 年 10 月 24 日 © 允许规范转载 打赏 赞赏作者 支付宝微信 赞 1 如果觉得我的文章对你有用,请随意赞赏
2 条评论
我们矿山也需要这个,能不能嵌入项目?
可以做,dog你可以试试