【轉載】Java Restful API 文檔生成工具 smart-doc

誰說生成api文檔就必需要定義註解？
誰說生成接口請求和返回示例必需要在線？

用代碼去探路，不斷嘗試更多文檔交付的可能性。
若是代碼有生命，爲何不換種方式和它對話！

1、背景

沒有背景、就本身作本身的背景

在當今各類盛行的先後端分離、restful service開發過程當中，接口文檔是必不
可少的。對於先後端分離的開發中，後端開發須要將接口寫好後須要告訴前端工程師接口的請求參數、響應示例等重要信息，而對於對外暴露的restful接口服務，咱們提供接口也是須要具有相同的接口文檔的。

可是對於後端工程師來說，寫接口文檔將變成一個很大的工做量，雖然如今有相似apidoc、swagger這樣的主流接口文檔生成工具，可是若是實際用過，會發現這些工具不能知足實際需求，這裏拿swagger爲例，這個工具最大的優勢能是提供在線的api文檔，可是它天生就有很強的代碼侵入性，要獲得一個基本知足需求的api接口文檔，必須在代碼中使用swagger自定義的註解。這其實給開發人員增長學習成本和工做量，而且就算你使用大量的註解，有許多接口仍是沒法知足。所以不得不去作一次接口文檔工具從新啓航探索，smart-doc應允而生，用代碼去探路，消除繁雜的註解，發現天下沒有難寫接口文檔。

2、smart-doc簡介

簡約而不簡單

smart-doc是基於java開發用於解決java web restful接口文檔書寫難和生成難的問題，固然api-doc也是一款零註解徹底基於源代碼接口定義，使用java標準註釋生成接口文檔的工具。而且smart-doc代碼也是徹底開源的。目前生成的文檔格式爲markdown。

api-doc的碼雲倉庫連接

github倉庫地址連接

3、功能特性

一個都不能少

• 零註解、零學習成本、只須要寫標準java註釋。
• 基於源代碼接口定義自動推導
• 支持springmvc、springboot
• 目前支持javabean上定義的部分fastjson和jackson註解
• 支持javabean上基於jsr303參數檢驗判斷參數是否爲必須
• 對json請求參數的接口可以自動生成模擬json參數
• 對一些經常使用字段定義可以生成有效的模擬值
• 支持生成json返回值示例
• 支持從項目外部加載源代碼來生成字段註釋
• 一款代碼註解檢測工具，明眼leader都知道接口文檔直接反饋出注釋狀況
• 支持將錯誤碼列表和全接口生成合併到一個markdown中
  4、效率成效

效率是作好工做的靈魂。——切斯特菲爾德

• 直接生成模擬請求參數，提高了團隊裏的前端和測試的工做效率，試想你讓他們去編寫json請求參數，若是你不寫，鬼知道是什麼樣。
• 後端開發只需專一業務和寫好標準註釋，無需引入額外註解，無需本身編寫請求參數示例和響應示例。
• 接口文檔更加標準化
  5、缺點

只有看到本身的不足，才能得到進步。

• 因爲基於源代碼分析生成文檔，所以沒法生成在線文檔，須要結合地方markdown文檔管理工具來管理。
• 因爲源代碼分析難度很大，針對不少代碼存在潛在的大量的bug.
• 對泛型返回接口須要明肯定義泛型定義，不然沒法推導
  6、用例

<dependency>
    <groupId>com.github.shalousun</groupId>
    <artifactId>api-doc</artifactId>
    <version>0.5</version>
</dependency>

6.1 定義bean

/**
 * @author yu 2018/8/4.
 */
public class SimpleUser {

    /**
     * 用戶名
     */
    @NotNull
    private String username;

    /**
     * 密碼
     */
    private String password;

    /**
     * 暱稱
     */
    private String nickName;

    /**
     * 電話
     */
    private String mobile;

}

6.2 定義接口

/**
 * 用戶信息操做接口
 * @author yu 2018/8/4.
 */

@RestController
@RequestMapping("/user")
public class UserController {

    /**
     * 添加用戶
     * @param user
     * @return
     */
    @PostMapping("/add")
    public List<SimpleUser> addUser(@RequestBody SimpleUser user){
        return null;
    }
}

啓動文檔生成

/**
 * 包括設置請求頭，缺失註釋的字段批量在文檔生成期使用定義好的註釋
 */
@Test
public void testBuilderControllersApi() {
    ApiConfig config = new ApiConfig();
    config.setServerUrl("http://localhost:8080");
    config.setStrict(true);
    config.setOutPath("d:\\md");
    //不指定SourcePaths默認加載代碼爲項目src/main/java下的,若是項目的某一些實體來自外部代碼能夠一塊兒加載
    config.setSourcePaths(
            SourcePath.path().setDesc("本項目代碼").setPath("src/main/java")

           //  SourcePath.path().setPath("E:\\Test\\Mybatis-PageHelper-master\\src\\main\\java"),
           // SourcePath.path().setDesc("加載項目外代碼").setPath("E:\\ApplicationPower\\ApplicationPower\\Common-util\\src\\main\\java")
    );

    long start = System.currentTimeMillis();
    ApiDocBuilder.builderControllersApi(config);
    long end = System.currentTimeMillis();
    DateTimeUtil.printRunTime(end, start);
}

生成文檔

添加用戶

URL: http://localhost:8080/user/add

Type: post

Content-Type: application/json; charset=utf-8

Request-parameters:

Parameter	Type	Description	Required
username	string	用戶名	true
password	string	密碼	false
nickName	string	暱稱	false
mobile	string	電話	false

Request-example:

{
    "username":"瑞霖.張",
    "password":"xud2qc",
    "nickName":"rudy.goyette",
    "mobile":"15650966307"
}

Response-fields:

Field	Type	Description
username	string	用戶名
password	string	密碼
nickName	string	暱稱
mobile	string	電話

Response-example:

[
    {
        "username":"浩然.閻",
        "password":"dzlv56",
        "nickName":"kieran.herzog",
        "mobile":"17863739656"
    }
]

demo地址：https://github.com/shalousun/api-doc-test

7、將來定義

期待下一次咱們更好的相遇

• 修改源代碼解析的衆多的bug
• 收集使用者的建議，提供非json請求參數的請求示例
• 收集使用者一些新增功能建議，增長一些必須功能。

8、使用協議

尊重別人，才能讓人尊敬。——笛卡爾

• 任何企業和我的不得用於申請專利

9、使用反饋

分享是一種生活的信念，明白了分享的同時，明白了存在的意義。

smart-doc的發展離不開你的支持，由於出於徹底的開源免費，所以您能夠基於smart-doc的源碼解析核心上去作一些自定義的開發來將接口文檔數據接入到一些第三方的在線api文檔管理系統，例如：CrapApi，可是在請使用者能有一份開源的心態和情懷，積極反饋api-doc的核心代碼使用bug和提出改善意見。<br/>
因爲我我的的開發精力有限，對因而否會將smart-doc快速集成推送到第三方優秀的管理工具，短時間內可能不會考慮，所以也但願使用者分享一些比較好的集成方案來供你們使用，若是方案比較符合smart-doc使用簡潔的核心理念，將會直接歸入後續的版本升級中，同時源代碼和方案提供者也將歸入smart-doc的開發者。

10、祝福

願你編寫接口無數，歸來還是少年

做者：慕先生5555510連接：http://www.imooc.com/article/71788來源：慕課網