From dc061d6ad79ab072312fd0e2a5acb3e0032b14c3 Mon Sep 17 00:00:00 2001 From: duanledexianxianxian Date: Fri, 27 Mar 2020 19:12:39 +0800 Subject: [PATCH] =?UTF-8?q?=E7=94=9F=E6=88=90markdown=20api=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../description/ArrayTypeDescription.java | 3 + .../description/ObjectTypeDescription.java | 3 + .../description/PrimitiveTypeDescription.java | 14 +- .../description/StringTypeDescription.java | 9 ++ .../common/description/TypeDescription.java | 92 ++++++++++++ .../com/kim/apidoc/example/common/User.java | 2 +- .../apidoc/example/spring/BaseController.java | 11 -- .../spring/advanced/AuthController.java | 26 ---- .../spring/advanced/EmptyController.java | 16 -- .../spring/advanced/IgnoreController.java | 20 --- .../spring/advanced/KimUserController.java | 2 +- .../spring/advanced/PageController.java | 141 ------------------ .../spring/advanced/UserController.java | 140 ----------------- .../apidoc/example/spring/hello/Greeting.java | 26 ---- .../spring/hello/GreetingController.java | 44 ------ 15 files changed, 122 insertions(+), 427 deletions(-) delete mode 100644 apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/BaseController.java delete mode 100644 apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/AuthController.java delete mode 100644 apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/EmptyController.java delete mode 100644 apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/IgnoreController.java delete mode 100644 apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/PageController.java delete mode 100644 apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/UserController.java delete mode 100644 apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/hello/Greeting.java delete mode 100644 apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/hello/GreetingController.java diff --git a/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/ArrayTypeDescription.java b/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/ArrayTypeDescription.java index 6ce2452..4b05db0 100644 --- a/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/ArrayTypeDescription.java +++ b/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/ArrayTypeDescription.java @@ -7,6 +7,9 @@ import com.fasterxml.jackson.databind.node.ArrayNode; import java.util.ArrayList; import java.util.Collection; +/** + * 数组类型描述 + */ public class ArrayTypeDescription extends TypeDescription { protected ArrayNode value; diff --git a/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/ObjectTypeDescription.java b/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/ObjectTypeDescription.java index d3a07c7..cdb571f 100644 --- a/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/ObjectTypeDescription.java +++ b/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/ObjectTypeDescription.java @@ -10,6 +10,9 @@ import lombok.Setter; import java.util.Collection; import java.util.List; +/** + * 对象类型描述 + */ @Setter @Getter public class ObjectTypeDescription extends TypeDescription { diff --git a/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/PrimitiveTypeDescription.java b/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/PrimitiveTypeDescription.java index 56d88b2..84e53a5 100644 --- a/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/PrimitiveTypeDescription.java +++ b/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/PrimitiveTypeDescription.java @@ -3,9 +3,16 @@ package com.kim.apidoc.core.common.description; import com.github.javaparser.resolution.types.ResolvedPrimitiveType; import com.github.javaparser.resolution.types.ResolvedReferenceType; - +/** + * 原始类型描述 + */ public class PrimitiveTypeDescription extends TypeDescription { + /** + * Instantiates a new Primitive type description. + * + * @param referenceType the reference type + */ public PrimitiveTypeDescription(ResolvedReferenceType referenceType) { switch (referenceType.getId()) { case "java.lang.Byte": @@ -44,6 +51,11 @@ public class PrimitiveTypeDescription extends TypeDescription { } + /** + * Instantiates a new Primitive type description. + * + * @param resolvedPrimitiveType the resolved primitive type + */ public PrimitiveTypeDescription(ResolvedPrimitiveType resolvedPrimitiveType) { type = resolvedPrimitiveType.describe(); switch (resolvedPrimitiveType) { diff --git a/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/StringTypeDescription.java b/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/StringTypeDescription.java index 81ba7db..021bd95 100644 --- a/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/StringTypeDescription.java +++ b/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/StringTypeDescription.java @@ -1,7 +1,16 @@ package com.kim.apidoc.core.common.description; +/** + * 字符串类型 + */ public class StringTypeDescription extends TypeDescription { + /** + * Instantiates a new String type description. + * + * @param type the type + * @param charSequence the char sequence + */ public StringTypeDescription(String type, CharSequence charSequence) { this.type = type; value = charSequence.toString(); diff --git a/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/TypeDescription.java b/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/TypeDescription.java index 16ff69a..88debb1 100644 --- a/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/TypeDescription.java +++ b/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/TypeDescription.java @@ -8,59 +8,141 @@ import lombok.Setter; import java.util.Collection; +/** + * The type Type description. + */ @Setter @Getter public abstract class TypeDescription { + /** + * The Prefix. + */ protected String prefix = ""; + /** + * The Key. + */ protected String key = ""; + /** + * The Type. + */ protected String type; + /** + * The Condition. + */ protected StringBuilder condition = new StringBuilder(); + /** + * 说明. + */ protected String remark; + /** + * 值. + */ protected Object value; + /** + * 默认值. + */ protected Object defaultValue; + /** + * 是否必填. + */ protected Boolean required; + /** + * Is available boolean. + * + * @return the boolean + */ public boolean isAvailable() { return !isUnAvailable(); } + /** + * Is un available boolean. + * + * @return the boolean + */ public boolean isUnAvailable() { return this instanceof UnAvailableTypeDescription; } + /** + * Is primitive boolean. + * + * @return the boolean + */ public boolean isPrimitive() { return this instanceof PrimitiveTypeDescription; } + /** + * As primitive primitive type description. + * + * @return the primitive type description + */ public PrimitiveTypeDescription asPrimitive() { return (PrimitiveTypeDescription) this; } + /** + * Is string boolean. + * + * @return the boolean + */ public boolean isString() { return this instanceof StringTypeDescription; } + /** + * As string string type description. + * + * @return the string type description + */ public StringTypeDescription asString() { return (StringTypeDescription) this; } + /** + * Is array boolean. + * + * @return the boolean + */ public boolean isArray() { return this instanceof ArrayTypeDescription; } + /** + * As array array type description. + * + * @return the array type description + */ public ArrayTypeDescription asArray() { return (ArrayTypeDescription) this; } + /** + * Is object boolean. + * + * @return the boolean + */ public boolean isObject() { return this instanceof ObjectTypeDescription; } + /** + * As object object type description. + * + * @return the object type description + */ public ObjectTypeDescription asObject() { return (ObjectTypeDescription) this; } + /** + * Add remark. + * + * @param value the value + */ public void addRemark(String value) { if (value == null) { return; @@ -72,10 +154,20 @@ public abstract class TypeDescription { } } + /** + * Full key string. + * + * @return the string + */ public String fullKey() { return StringHelper.join(".", prefix, key); } + /** + * Rows collection. + * + * @return the collection + */ public Collection rows() { String key = fullKey(); if (StringHelper.isBlank(key)) { diff --git a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/common/User.java b/apidoc-springmvc/src/test/java/com/kim/apidoc/example/common/User.java index 115ce7a..317cda9 100644 --- a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/common/User.java +++ b/apidoc-springmvc/src/test/java/com/kim/apidoc/example/common/User.java @@ -11,7 +11,7 @@ import java.util.Date; import java.util.List; /** - * The type User. + * 用户对象 */ @Setter @Getter diff --git a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/BaseController.java b/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/BaseController.java deleted file mode 100644 index d32ddfd..0000000 --- a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/BaseController.java +++ /dev/null @@ -1,11 +0,0 @@ -package com.kim.apidoc.example.spring; - -import org.springframework.web.bind.annotation.RequestMapping; - -/** - * 示例controller继承的情况 - * 子类继承父类的路径 - */ -@RequestMapping("/restdoc") -public class BaseController { -} diff --git a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/AuthController.java b/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/AuthController.java deleted file mode 100644 index 8926ca5..0000000 --- a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/AuthController.java +++ /dev/null @@ -1,26 +0,0 @@ -package com.kim.apidoc.example.spring.advanced; - -import com.kim.apidoc.example.common.ResultData; -import com.kim.apidoc.example.spring.BaseController; -import org.springframework.stereotype.Controller; -import org.springframework.web.bind.annotation.*; - -/** - * @ignore - * @index 3 - */ -@Controller -@RequestMapping("/auth") -public class AuthController extends BaseController{ - - /** - * - * @param token 上报的身份验证token，jwt - * @return - */ - @PostMapping - public ResultData auth(@RequestHeader() String token){ - return ResultData.ok(); - } - -} diff --git a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/EmptyController.java b/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/EmptyController.java deleted file mode 100644 index be7f38f..0000000 --- a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/EmptyController.java +++ /dev/null @@ -1,16 +0,0 @@ -package com.kim.apidoc.example.spring.advanced; - -import org.springframework.web.bind.annotation.RequestMapping; -import org.springframework.web.bind.annotation.RestController; - -/** - * @ignore - * will be ignore - */ -@RestController -@RequestMapping("/empty") -public class EmptyController { - - - -} diff --git a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/IgnoreController.java b/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/IgnoreController.java deleted file mode 100644 index 2ff3b75..0000000 --- a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/IgnoreController.java +++ /dev/null @@ -1,20 +0,0 @@ -package com.kim.apidoc.example.spring.advanced; - -import org.springframework.web.bind.annotation.RequestMapping; -import org.springframework.web.bind.annotation.RestController; - -/** - * will be ignore - * @ignore - */ -@RestController -@RequestMapping("/ignore") -public class IgnoreController { - - - @RequestMapping - public void ignoreThis(){ - } - - -} diff --git a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/KimUserController.java b/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/KimUserController.java index dd1ab59..5f202ad 100644 --- a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/KimUserController.java +++ b/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/KimUserController.java @@ -26,7 +26,7 @@ public class KimUserController { * 主动根据id获取用户的信息 * * @param id 用户编号 - * @return result data + * @return 用户数据 */ @GetMapping(value = "/{id}") public ResultData detail(@PathVariable String id) { diff --git a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/PageController.java b/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/PageController.java deleted file mode 100644 index 22e593a..0000000 --- a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/PageController.java +++ /dev/null @@ -1,141 +0,0 @@ -package com.kim.apidoc.example.spring.advanced; - -import com.apigcc.model.Info; -import com.apigcc.model.InfoQuery; -import com.kim.apidoc.example.common.*; -import com.kim.apidoc.example.spring.BaseController; -import com.kim.apidoc.example.spring.hello.Greeting; -import org.jruby.ir.Tuple; -import org.springframework.stereotype.Controller; -import org.springframework.web.bind.annotation.*; -import org.springframework.web.servlet.ModelAndView; - -import java.util.List; -import java.util.Map; - -/** - * @ignore - * @index 4 - */ -@Controller -@RequestMapping("/page") -public class PageController extends BaseController { - - /** - * 默认页面，由于不是restful的，restdoc将忽略该Endpoint - * - * @return - */ - @GetMapping - public ModelAndView index() { - return new ModelAndView(); - } - - /** - * Hello with ResponseBody - * ********* - * 由于带有@ResponseBody，restdoc将解析该Endpoint - *

- * hhh - * \********* - * ********* - * hhhh - * ********* - *

- * class ************** { - *

- * } - * - * @return - */ - @GetMapping("/hello") - @ResponseBody - public Greeting hello() { - return new Greeting(1, "hello world"); - } - - - /** - * 未知的多泛型的tuple 演示 - * - * @return - */ - @GetMapping("/tuple") - @ResponseBody - public Tuple tuple() { - return null; - } - - /** - * 多个RequestMethod - * - * @return - */ - @RequestMapping(value = "/multiMethod", method = {RequestMethod.GET, RequestMethod.POST, RequestMethod.PUT}) - @ResponseBody - public ResultData multiMethod() { - return null; - } - - @PostMapping("/multi") - @ResponseBody - public ResultData> multi(@RequestBody ResultData>> resultData) { - return null; - } - - - /** - * 引用二方Jar - * 使用二方Jar的类时，代码解析器无法获取类上的注释，注解 - * 只能获取属性的名称和类型 - * @param infoQuery - * @return - */ - @PostMapping("/jar") - @ResponseBody - public Info jar(@RequestBody InfoQuery infoQuery){ - return null; - } - - - /** - * 一个复杂的类型 List> - * @return - */ - @GetMapping("/map") - @ResponseBody - public List> map(){ - return null; - } - - /** - * 一个更复杂的类型 List>>> - * @return - */ - @GetMapping("/map") - @ResponseBody - public List>>> maps(){ - return null; - } - - /** - * 一个问号类型 List>> - * @return - */ - @GetMapping("/map") - @ResponseBody - public List>> maps1(){ - return null; - } - - - /** - * 多级菜单 - * @return - */ - @GetMapping("/menus") - @ResponseBody - public List

menus(){ - return null; - } -} diff --git a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/UserController.java b/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/UserController.java deleted file mode 100644 index c86d7d8..0000000 --- a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/UserController.java +++ /dev/null @@ -1,140 +0,0 @@ -package com.kim.apidoc.example.spring.advanced; - -import com.kim.apidoc.example.common.*; -import com.kim.apidoc.example.spring.BaseController; -import org.springframework.http.ResponseEntity; -import org.springframework.ui.Model; -import org.springframework.web.bind.annotation.*; - -import java.util.List; - -/** - * @ignore - * 用户模块（标题） - * 用户示例模块文字描述（详情） - * 支持多行文字 - * @index 2 - */ -@RestController -@RequestMapping("/users") -public class UserController extends BaseController { - - /** - * 用户详情信息 - * 主动根据id获取用户的信息 - * - * @param id 用户编号 - * @return - */ - @GetMapping(value = "/{id}") - public ResultData detail(@PathVariable String id) { - User user = new User(); - return ResultData.ok(user); - } - - /** - * 用户详情信息（根据email或电话号码） - * 多路径适配 - * - * @param email - * @param phone - * @return - */ - @GetMapping(value = {"/detail", "/info"}) - public ResultData detailOrInfo(String email, String phone) { - return ResultData.ok(new User()); - } - - /** - * 用户信息新增 - * - * @param user 用户信息 - * @return - */ - @PostMapping - public ResultData add(@RequestBody UserDTO user) { - return ResultData.ok(); - } - - /** - * 用户信息更新 - * - * @param user 用户信息 - * @return - */ - @PatchMapping - public ResultData update(@RequestBody UserDTO user) { - return ResultData.ok(); - } - - /** - * 用户列表信息查询 - * 默认展示GET方法查询 - * 返回集合类的结果 - * - * @param page 页码 - * @param size 每页条数 - * @return - */ - @RequestMapping("/list") - public ResultData> list(@RequestParam(defaultValue = "1") int page, @RequestParam(defaultValue = "20") int size) { - return ResultData.ok(); - } - - /** - * 用户列表信息搜索 - * POST搜索时，请求参数将放在请求体中 - * - * @param userQuery 查询参数 - * @return - */ - @PostMapping("/search") - public ResultData> search(UserQuery userQuery) { - return ResultData.ok(); - } - - /** - * 用户信息删除 - * ResponseEntity、Model以及未知类型将忽略 - * - * @param id - * @return - */ - @RequestMapping(value = "/{id}", method = RequestMethod.DELETE) - public ResponseEntity delete(@PathVariable String id, Model model) { - return ResponseEntity.ok(ResultData.ok()); - } - - /** - * 用户禁用 - * 某些项目使用自定义的ArgumentResolver，让spring自动注入一些信息 - * restdoc在解析时，可通过env.ignoreTypes("UserDtails")来忽略这些 - * - * @param userDetails 当前登录用户的信息 - * @return - */ - @RequestMapping(value = "/{id}/disable", method = RequestMethod.PUT) - public ResultData disable(UserDetails userDetails) { - return ResultData.ok(); - } - - /** - * 查询角色下的用户总数 - * @param role 枚举类型{@link Role} - * @return - */ - @GetMapping("/role") - public ResultData listFromRole(Role role){ - return ResultData.ok(); - } - - /** - * 批量上传用户信息 - * @param list - * @return com.apigcc.example.common.UserDTO - */ - @PostMapping("/batch") - public void batch(@RequestBody List list){ - } - -} diff --git a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/hello/Greeting.java b/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/hello/Greeting.java deleted file mode 100644 index e0412f9..0000000 --- a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/hello/Greeting.java +++ /dev/null @@ -1,26 +0,0 @@ -package com.kim.apidoc.example.spring.hello; - -public class Greeting { - - /** - * 编号 - */ - private final long id; - /** - * 内容 - */ - private final String content; - - public Greeting(long id, String content) { - this.id = id; - this.content = content; - } - - public long getId() { - return id; - } - - public String getContent() { - return content; - } -} diff --git a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/hello/GreetingController.java b/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/hello/GreetingController.java deleted file mode 100644 index 6769413..0000000 --- a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/hello/GreetingController.java +++ /dev/null @@ -1,44 +0,0 @@ -package com.kim.apidoc.example.spring.hello; - -import org.springframework.web.bind.annotation.RequestMapping; -import org.springframework.web.bind.annotation.RequestParam; -import org.springframework.web.bind.annotation.RestController; - -import java.util.concurrent.atomic.AtomicLong; - -/** - * 欢迎使用Apiggs - * @ignore - * @author fengyuchenglun - * @version 1.0.0 - * @index 1 - */ -@RestController -public class GreetingController { - - /** - * The constant template. - */ - private static final String template = "Hello, %s!"; - /** - * The Counter. - */ - private final AtomicLong counter = new AtomicLong(); - - /** - * 示例接口 - * 自定义错误编码 - * - * @param name 名称 - * @return greeting greeting - * @errorCode ERROR_CODE_1 错误编码1 很长很长的描述 - * @errorCode ERROR_CODE_2 错误编码2 很长很长的描述 - * @errorCode ERROR_CODE_3 错误编码3 很长很长的描述很长很长的描述很长很长的描述很长很长的描述很长很长的描述很长很长的描述 - * @errorCode ERROR_CODE_4 错误编码4 很长很长的描述很长很长的描述很长很长的描述很长很长的描述很长很长的描述很长很长的描述很长很长的描述很长很长的描述很长很长的描述 - */ - @RequestMapping("/greeting") - public Greeting greeting(@RequestParam(value = "name", defaultValue = "apigcc") String name) { - return new Greeting(counter.incrementAndGet(), - String.format(template, name)); - } -} -- GitLab