生成markdown api文档

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;

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 {

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) {

apidoc-core/src/main/java/com/kim/apidoc/core/common/description/StringTypeDescription.java

 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();

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<Row> rows() {
         String key = fullKey();
         if (StringHelper.isBlank(key)) {

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

apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/BaseController.java

-package com.kim.apidoc.example.spring;
-
-import org.springframework.web.bind.annotation.RequestMapping;
-
-/**
- * 示例controller继承的情况
- * 子类继承父类的路径
- */
-@RequestMapping("/restdoc")
-public class BaseController {
-}

apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/AuthController.java

-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();
-    }
-
-}

apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/EmptyController.java

-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 {
-
-
-
-}

apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/IgnoreController.java

-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(){
-    }
-
-
-}

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<User> detail(@PathVariable String id) {

apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/PageController.java

-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
-     * <p>
-     * hhh
-     * \*********
-     *  *********
-     * hhhh
-     * *********
-     * <p>
-     * class ************** {
-     * <p>
-     * }
-     *
-     * @return
-     */
-    @GetMapping("/hello")
-    @ResponseBody
-    public Greeting hello() {
-        return new Greeting(1, "hello world");
-    }
-
-
-    /**
-     * 未知的多泛型的tuple 演示
-     *
-     * @return
-     */
-    @GetMapping("/tuple")
-    @ResponseBody
-    public Tuple<UserDTO, User> 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<Wrapper<UserDTO>> multi(@RequestBody ResultData<Wrapper<List<UserDTO>>> resultData) {
-        return null;
-    }
-
-
-    /**
-     * 引用二方Jar
-     * 使用二方Jar的类时，代码解析器无法获取类上的注释，注解
-     * 只能获取属性的名称和类型
-     * @param infoQuery
-     * @return
-     */
-    @PostMapping("/jar")
-    @ResponseBody
-    public Info jar(@RequestBody InfoQuery infoQuery){
-        return null;
-    }
-
-
-    /**
-     * 一个复杂的类型 List<Map<String,User>>
-     * @return
-     */
-    @GetMapping("/map")
-    @ResponseBody
-    public List<Map<String,User>> map(){
-        return null;
-    }
-
-    /**
-     * 一个更复杂的类型 List<Map<String,ResultData<Map<Integer,User>>>>
-     * @return
-     */
-    @GetMapping("/map")
-    @ResponseBody
-    public List<Map<String,ResultData<Map<Integer,User>>>> maps(){
-        return null;
-    }
-
-    /**
-     * 一个问号类型 List<Map<String,List<?>>>
-     * @return
-     */
-    @GetMapping("/map")
-    @ResponseBody
-    public List<Map<String,List<?>>> maps1(){
-        return null;
-    }
-
-
-    /**
-     * 多级菜单
-     * @return
-     */
-    @GetMapping("/menus")
-    @ResponseBody
-    public List<Menu> menus(){
-        return null;
-    }
-}

apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/UserController.java

-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<User> detail(@PathVariable String id) {
-        User user = new User();
-        return ResultData.ok(user);
-    }
-
-    /**
-     * 用户详情信息（根据email或电话号码）
-     * 多路径适配
-     *
-     * @param email
-     * @param phone
-     * @return
-     */
-    @GetMapping(value = {"/detail", "/info"})
-    public ResultData<User> 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<User>> list(@RequestParam(defaultValue = "1") int page, @RequestParam(defaultValue = "20") int size) {
-        return ResultData.ok();
-    }
-
-    /**
-     * 用户列表信息搜索
-     * POST搜索时，请求参数将放在请求体中
-     *
-     * @param userQuery 查询参数
-     * @return
-     */
-    @PostMapping("/search")
-    public ResultData<List<User>> search(UserQuery userQuery) {
-        return ResultData.ok();
-    }
-
-    /**
-     * 用户信息删除
-     * ResponseEntity、Model以及未知类型将忽略
-     *
-     * @param id
-     * @return
-     */
-    @RequestMapping(value = "/{id}", method = RequestMethod.DELETE)
-    public ResponseEntity<ResultData> 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<Integer> listFromRole(Role role){
-        return ResultData.ok();
-    }
-
-    /**
-     * 批量上传用户信息
-     * @param list
-     * @return com.apigcc.example.common.UserDTO
-     */
-    @PostMapping("/batch")
-    public void batch(@RequestBody List<UserDTO> list){
-    }
-
-}

apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/hello/Greeting.java

-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;
-    }
-}

apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/hello/GreetingController.java

-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));
-    }
-}