Skip to content

Commit 60a9dd5

Browse files
YunaiVYunaiV
committed
使用 showdoc 生成接口文档
1 parent baf8bca commit 60a9dd5

File tree

4 files changed

+92
-2
lines changed

4 files changed

+92
-2
lines changed

‎lab-24/lab-24-apidoc-showdoc/showdoc_api.sh

+64
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
#! /bin/bash
2+
#
3+
# 文档说明： https://www.showdoc.com.cn/page/741656402509783
4+
#
5+
api_key="60fc53cea6af4758c1686cb22ba20566472255580" #api_key
6+
api_token="0bbb5f564a9ee66333115b1abb8f8d541979489118" #api_token
7+
url="https://www.showdoc.com.cn/server/?s=/api/open/fromComments" #同步到的url。使用www.showdoc.com.cn的不需要修改，使用私有版的请修改
8+
#
9+
#
10+
#
11+
#
12+
#
13+
# 如果第一个参数是目录，则使用参数目录。若无，则使用脚本所在的目录。
14+
if [[ -z "$1" ]] || [[ ! -d "$1" ]] ; then #目录判断，如果$1不是目录或者是空，则使用当前目录
15+
curren_dir=$(dirname $(readlink -f $0))
16+
else
17+
curren_dir=$(cd $1; pwd)
18+
fi
19+
#echo "$curren_dir"
20+
# 递归搜索文件
21+
searchfile() {
22+
23+
old_IFS="$IFS"
24+
IFS=$'\n' #IFS修改
25+
for chkfile in $1/*
26+
do
27+
filesize=`ls -l $chkfile | awk '{ print $5 }'`
28+
maxsize=$((1024*1024*1)) # 1M以下的文本文件才会被扫描
29+
if [[ -f "$chkfile" ]] && [ $filesize -le $maxsize ] && [[ -n $(file $chkfile | grep text) ]] ; then # 只对text文件类型操作
30+
echo "正在扫描 $chkfile"
31+
result=$(sed -n -e '/\/\*\*/,/\*\//p' $chkfile | grep showdoc) # 正则匹配
32+
if [ ! -z "$result" ] ; then
33+
txt=$(sed -n -e '/\/\*\*/,/\*\//p' $chkfile)
34+
#echo "sed -n -e '/\/\*\*/,/\*\//p' $chkfile"
35+
#echo $result
36+
if [[ $txt =~ "@url" ]] && [[ $txt =~ "@title" ]]; then
37+
echo -e "\033[32m $chkfile 扫描到内容 , 正在生成文档 \033[0m "
38+
txt2=${txt//&/_this_and_change_}
39+
# 通过接口生成文档
40+
curl -H 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' "${url}" --data-binary @- <<CURL_DATA
41+
from=shell&api_key=${api_key}&api_token=${api_token}&content=${txt2}
42+
CURL_DATA
43+
fi
44+
fi
45+
fi
46+
47+
if [[ -d $chkfile ]] ; then
48+
searchfile $chkfile
49+
fi
50+
done
51+
IFS="$old_IFS"
52+
}
53+
54+
55+
#执行搜索
56+
searchfile $curren_dir
57+
58+
59+
#
60+
sys=$(uname)
61+
if [[ $sys =~ "MS" ]] || [[ $sys =~ "MINGW" ]] || [[ $sys =~ "win" ]] ; then
62+
read -s -n1 -p "按任意键继续 ... " # win环境下为照顾用户习惯，停顿一下
63+
fi
64+

‎lab-24/lab-24-apidoc-showdoc/src/main/java/cn/iocoder/springboot/lab24/apidoc/controller/UserController.java

+24-2
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,6 @@
44
import cn.iocoder.springboot.lab24.apidoc.controller.vo.UserLoginRespVO;
55
import org.springframework.web.bind.annotation.*;
66

7-
import java.util.ArrayList;
8-
97
@RestController
108
@RequestMapping("/users")
119
public class UserController {
@@ -19,4 +17,28 @@ public UserLoginRespVO login(@RequestBody UserLoginReqVO reqVO) {
1917
return respVO;
2018
}
2119

20+
/**
21+
* showdoc
22+
* @title 用户登录
23+
* @description 用户登录的接口
24+
* @url http://127.0.0.1:8080/user/login2
25+
* @method POST
26+
* @json_param {"username": "yudaoyuanma", "password": "yunai"}
27+
* @param username 必选 string 用户名
28+
* @param password 必选 string 密码
29+
* @return { "userId": 1024, "name": "芋道源码", "username": "yudaoyuanma" }
30+
* @return_param userId 必选 number 用户编号
31+
* @return_param name 必选 string 用户昵称
32+
* @return_param username 必选 string 用户账号
33+
* @remark 我就是快乐的备注
34+
*/
35+
@PostMapping("/login2")
36+
public UserLoginRespVO login2(@RequestBody UserLoginReqVO reqVO) {
37+
UserLoginRespVO respVO = new UserLoginRespVO();
38+
respVO.setUserId(1024);
39+
respVO.setUsername(reqVO.getUsername());
40+
respVO.setName("芋道源码");
41+
return respVO;
42+
}
43+
2244
}

‎lab-24/lab-24-apidoc-showdoc/src/main/java/cn/iocoder/springboot/lab24/apidoc/controller/vo/UserLoginReqVO.java

+3
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22

33
public class UserLoginReqVO {
44

5+
/**
6+
* 用户名
7+
*/
58
private String username;
69

710
private String password;

‎lab-24/lab-24-apidoc-showdoc/swagger.json

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{"swagger":"2.0","info":{"description":"我是一段描述","version":"1.0.0","title":"测试接口文档示例","contact":{"name":"芋艿","url":"http://www.iocoder.cn","email":"zhijiantianya@gmail.com"}},"host":"127.0.0.1:8080","basePath":"/","tags":[{"name":"用户 API 接口","description":"User Controller"}],"paths":{"/users/add":{"post":{"tags":["用户 API 接口"],"summary":"添加用户","operationId":"addUsingPOST","consumes":["application/json"],"produces":["*/*"],"parameters":[{"name":"password","in":"query","description":"密码","required":true,"type":"string","x-example":"nicai"},{"name":"username","in":"query","description":"账号","required":true,"type":"string","x-example":"yudaoyuanma"}],"responses":{"200":{"description":"OK","schema":{"type":"integer","format":"int32"}},"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/users/delete":{"post":{"tags":["用户 API 接口"],"summary":"删除指定用户编号的用户","operationId":"deleteUsingPOST","consumes":["application/json"],"produces":["*/*"],"parameters":[{"name":"id","in":"query","description":"用户编号","required":true,"type":"integer","format":"int32","x-example":1024}],"responses":{"200":{"description":"OK","schema":{"type":"boolean"}},"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/users/get":{"get":{"tags":["用户 API 接口"],"summary":"获得指定用户编号的用户","operationId":"getUsingGET","produces":["*/*"],"parameters":[{"name":"id","in":"query","description":"用户编号","required":true,"type":"integer","format":"int32","x-example":1024}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/用户 VO"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/users/list":{"get":{"tags":["用户 API 接口"],"summary":"查询用户列表","description":"目前仅仅是作为测试，所以返回用户全列表","operationId":"listUsingGET","produces":["*/*"],"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/用户 VO"}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/users/update":{"post":{"tags":["用户 API 接口"],"summary":"更新指定用户编号的用户","operationId":"updateUsingPOST","consumes":["application/json"],"produces":["*/*"],"parameters":[{"name":"id","in":"query","description":"用户编号","required":true,"type":"integer","format":"int32","x-example":1024},{"name":"password","in":"query","description":"密码","required":true,"type":"string","x-example":"nicai"},{"name":"username","in":"query","description":"账号","required":true,"type":"string","x-example":"yudaoyuanma"}],"responses":{"200":{"description":"OK","schema":{"type":"boolean"}},"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}}},"definitions":{"用户 VO":{"type":"object","required":["id","username"],"properties":{"id":{"type":"integer","format":"int32","example":1024,"description":"用户编号"},"username":{"type":"string","example":"yudaoyuanma","description":"账号"}},"title":"用户 VO"}}}

0 commit comments

Comments
 (0)