代碼零入侵的文檔生成工具,通過解析.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);
   }
}

個人代碼,未經過嚴格測試,如使用過程中有任何問題請在評論中@我,如果看到會及時修復