您的輕量級api接口文檔生成助手【api4j】

0：前言

前段時間上班摸魚之餘，或者回家無事可幹，想着寫點開源小玩意能夠幫助本身平時的開發，想來想去就想着每次給別人提供接口都要手寫，swagger又過重太麻煩。就想着本身寫一個簡單點的，輕量點的小工具。

因而-----> api4j誕生了。

1：創做初衷

• 業務開發任務緊,手寫接口文檔麻煩!
• swagger用起來比較麻煩,代碼侵入較大,並且有一些類型嵌套的方面的不支持
• 能夠自定義輸出文檔的類型和結構去貼合本身公司的文檔類型
• 想幫助你們能夠輕鬆自由又舒服的生成接口文檔

2：目前提供的功能

• 支持springmvc的接口
• 支持dubbo-rest的接口
• 支持jsr和hibernate validator的校驗註解
• 支持泛型以及嵌套對象的輸出
• 能夠生成相應的模擬json請求報文以供調試(curl,postman等)
• 支持控制檯打印
• 支持輸出md文檔

3：Getting Started

3.1：添加maven依賴:

<dependency>
    <groupId>io.github.shijiawei110</groupId>
    <artifactId>api4j</artifactId>
    <version>1.1.0</version>
</dependency>
複製代碼

3.2：開始使用

1. 在您的mvc或者dubbo-rest等接口的class或者method(推薦)上添加註解@ApiTag
2. 推薦在method上添加註解
3. 註解參數可選填 : name[接口名],value[接口標註],author[接口做者]
4. 能夠在方法或者參數上添加註釋,生成文檔的時候會輸出註釋,可是@author @params 等的doc註釋不會被錄入輸出
5. 使用咱們 ApiDocUtil 工具類一鍵運行輸出

/**
     * 這是mvc get test註釋，註釋會被文檔輸出
     */
    @RequestMapping("/test")
    @ApiTag(name = "mvc測試接口", value = "這是mvc get test", author = "sjw")
    public Integer getTest1(@RequestParam(value = "test_name", required = false) String name) {
        return null;
    }
    
複製代碼

//直接使用便可,將會掃描當前項目下的帶有註解的類或者方法,輸出文檔打印到控制檯
	ApiDocUtil.makeApiDoc();
複製代碼

//須要輸出md文檔(默認生成路徑在項目路徑下的 /src/test/resources/apidoc)
	ApiDocUtil.makeApiDoc(ApiDocConf.defaultConf().mdSet());
	
	//若是須要指定輸出目錄
	ApiDocConf apiDocConf = new ApiDocConf().mdSet();
	apiDocConf.setDocOutputPath("/Users/download/apidoc");
	ApiDocUtil.makeApiDoc(apiDocConf);
複製代碼

//若是須要指定請求地址的公用根路徑:
	//好比 指定的請求url爲 /getTest/getName 會變成/service/getTest/getName
	ApiDocUtil.makeApiDoc(ApiDocConf.defaultConf("service").mdSet());
複製代碼

3.3：你能夠這樣定義一個你的入參或者出參

public class ParamDemo {
    /**
     * 在這裏寫字段含義的註釋能夠在文檔中輸出
     */
    @NotNull
    private Long id;

    @JsonProperty("test_id")
    @Min(1)
    @Max(5)
    private Long testId;

    /**
     * age  jackson註解能夠改變字段名
     */
    @JsonProperty("test_age")
    private Integer testAge;

    /**
     * 名稱
     */
    @Length(min = 1, max = 100)
    private String testName;

    @NotBlank
    private String ok;

    @NotEmpty
    @Size(min = 1, max = 10)
    private List<String> reqStrs;

    /**
     * 書籍實體類
     */
    private Book book;
}
複製代碼

3.4：若是你嫌麻煩不想在每一個項目依賴api4j,咱們能夠在當前項目指定去輸出其餘項目的接口文檔

//設置掃描的根路徑
       String rootPath = "/Users/javaproject/project";
       ApiDocConf apiDocConf = ApiDocConf.customConf(rootPath);
       //添加類名加方法名 中間用.隔開
       apiDocConf.addMethod("ClassName1.MethodName1");
       apiDocConf.addMethod("ClassName1.MethodName2");
       //同理能夠再控制檯或者md文檔輸出
       ApiDocUtil.makeApiDoc(apiDocConf);
複製代碼

4：將來開發計劃

• 支持對外網關接口的文檔生成
• 支持生成更加豐富的文檔形式(好比html等)

點擊->github地址

---

若是您使用了個人項目請給一個贊吧,怒求贊！若是有建議和BUG請聯繫我