代码零入侵的文档生成工具,通过解析.java文件生成rest-doc文档

GitHub Wiki 地址:

https://github.com/xuyuansheng/xbapi-maven-plugin/wiki

使用: 

1.添加依赖插件

<plugin>
    <groupId>com.github.xuyuansheng</groupId>
    <artifactId>xbapi-maven-plugin</artifactId>
    <version>1.1</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>rest-api</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <!--文档的标题,不写默认为项目名-->
        <title></title>
        <!--文档的版本号-->
        <version>1.2.1</version>
        <description>文档的描述,注意不是api,是针对整个文档的,可以不写,默认为空</description>
        <!--结果的输出路径,当路径为相对路径时,默认在target目录中-->
        <xbOutPutDir>xbApis</xbOutPutDir>
        <protocol>https</protocol>
        <host>localhost</host>
        <port>8080</port>
    </configuration>
</plugin>

2.使用过程中可能会用到@Apis注解,此注解获取方式可以让项目依赖这个插件或者自己创建一个@Apis注解.

2.1 使用依赖

 <dependencies>
   <dependency>
       <groupId>com.github.xuyuansheng</groupId>
       <artifactId>xbapi-maven-plugin</artifactId>
       <version>1.1</version>
   </dependency>
 </dependencies>

2.2 自己创建注解
  package cn.xuxiaobu.doc.apis.annotions;
  import java.lang.annotation.*;

  /**
  * 定义API的注解,类似于spring中的Controller或者RequestMapping等注解
  */
  @Target({ElementType.METHOD, ElementType.TYPE})
  @Retention(RetentionPolicy.RUNTIME)
  @Documented
  public @interface Apis {
    /** 名称  */
    String name() default "";
    /** url的值 */
    String value() default "";
    /** 方法支持的请求方式  */
    String[] method() default {};
    /** 方法参数  */
    Class<?>[] paramsType() default {};
    /** 方法的返回值  */
    Class<?> returnType() default Object.class;
    String[] params() default {};
    String[] headers() default {};
    String[] consumes() default {};
    String[] produces() default {};
  }

 

3.使用示例代码

package com.java.study.javastudy.controller;

import cn.xuxiaobu.doc.apis.annotions.Apis;
//import com.java.study.javastudy.annotations.Apis;
import org.springframework.web.bind.annotation.*;

import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.List;

/**
 * @program: java-study
 * @description: xbRest-doc文档
 * @author: Mr.Xu
 * @create: 2019/9/1 12:57
 */
@RestController
@RequestMapping("xbApiDocController")
@Apis
public class XbApiDocController {

    /**
     * 简单类型的参数和返回值模板
     *
     * @param name 参数名称 name
     * @return 返回值string
     */
    @PostMapping("/getString")
    public String getString(@RequestParam(required = false, value = "a") String name) {
        System.out.println(name);
        return "";
    }

    /**
     * 自定义对象类型的返回 和 自定义对象的参数
     *
     * @param xbApiParams  自定义对象参数
     * @param integerParam 简单参数Integer
     * @return 自定义返回对象
     */
    @GetMapping("/getResult")
    public XbApiResult getResult(@RequestParam(required = false, value = "a") XbApiParams xbApiParams, Integer integerParam) {
        System.out.println(xbApiParams);
        return null;
    }

    /**
     * 带泛型的自定义对象类型的返回 和 自定义对象的参数
     *
     * @param xbApiParams  自定义对象参数
     * @param integerParam 简单参数Integer
     * @return 自定义返回对象
     */
    @RequestMapping("/getResultGeneric")
    public ResultVo<XbApiResult> getResultGeneric(@RequestParam(required = false, value = "a") XbApiParams xbApiParams, Integer integerParam) {
        System.out.println(xbApiParams);
        return null;
    }

    /**
     * 返回值为void时的使用,添加@Apis注解,
     * returnType = XbApiResult.class 表示此返回的类型为XbApiResult.class
     * 注意:只有方法的返回为void时returnType才会生效
     * <p>
     * paramsType = {XbApiParams.class, HttpServletResponse.class, List.class}
     * String xbApiParams, HttpServletResponse response, Integer integerParams
     * 参数的注解值一定要和方法的参数一一对应,否则会出现解析错位,
     * 如: 如果把paramsType中的HttpServletResponse.class去掉,变成如此:paramsType = {XbApiParams.class,List.class},解析的结果就会把response参数的类型变为List.class
     *
     * @param xbApiParams   自定义对象参数,参数的类型为String,实际为一个自定义对象的json对象
     * @param response      httpServletResponse
     * @param integerParams 第三个参数,Integer类型变为List
     */
    @RequestMapping("/getVoidResult")
    @Apis(returnType = XbApiResult.class, paramsType = {XbApiParams.class, HttpServletResponse.class, List.class})
    public void getVoidResult(@RequestParam(required = false, value = "a") String xbApiParams, HttpServletResponse response, Integer integerParams) {
        System.out.println(xbApiParams + integerParams);
        try {
            /*  方法无返回值,用response手动println内容 */
            response.getWriter().println("");
        } catch (IOException e) {
            e.printStackTrace();
        }
    }

    /**
     * 如果是普通的Java项目可以使用@Apis注解标注url,参数,返回值的使用同上一个例子
     * 只有类上有此注解才能扫描到这个Url,并生效
     *
     * @param xbApiParams 参数
     * @return 返回一个List
     */
    @Apis("getApisUrl")
    public List getApisUrl(@RequestParam(required = false, value = "a") String xbApiParams) {
        System.out.println(xbApiParams);
        return null;
    }

}

4.执行插件

5.生成的结果

 

 

 

示例中用到的代码:

import lombok.Data;

/**
 * @program: java-study
 * @description: java类解析
 * @author: Mr.Xu
 * @create: 2019/9/1 12:59
 */
@Data
public class XbApiParams {
    /**
     * 索引,获取name
     */
    private String index;
    /**
     * 名称正则,匹配名称的规则
     */
    private Integer namePattern;
    /**
     * 参数的描述
     */
    private String desc;

}

 

import lombok.Data;

/**
 * @program: java-study
 * @description: java类解析
 * @author: Mr.Xu
 * @create: 2019/9/1 12:59
 */
@Data
public class XbApiResult {
    /**
     * 姓名
     */
    private String name;
    /**
     * 年龄
     */
    private Integer age;
    /**
     * 描述
     */
    private String desc;

}

 

import lombok.Data;

/**
 * @program: api-docconfig
 * @description: 结果类
 * @author: Mr.Xu
 * @create: 2019-05-29 11:13
 **/
@Data
public class ResultVo<T> {
   /** 是否成功获取到结果 */
   private boolean ifSuccess;
   /** 如果失败时的提示信息 */
   private String message;
   /** 结果数据 */
   private T data;


   public ResultVo(boolean ifSuccess, String message, T data) {
      this.ifSuccess = ifSuccess;
      this.message = message;
      this.data = data;
   }

   public static <T>ResultVo <T>  getSuccess(T data){
      return new <T>ResultVo(true, "success", data);
   }

   public static <T>ResultVo<T>  getFailed(String message,T data){
      return new <T>ResultVo(false, message, data);
   }
}

个人代码,未经过严格测试,如使用过程中有任何问题请在评论中@我,如果看到会及时修复