smart-doc是一個java restful api文檔生成工具，smart-doc顛覆了傳統(tǒng)類似swagger這種大量采用注解侵入來生成文檔的實現(xiàn)方法。smart-doc完全基于接口源碼分析來生成接口文檔，完全做到零注解侵入，你只需要按照java標準注釋的寫，smart-doc就能幫你生成一個簡易明了的markdown或是一個像GitBook樣式的靜態(tài)html文檔。
下面將介紹如何在Spring Boot項目中集成smart-doc生成一個簡明的api文檔。

江川網(wǎng)站制作公司哪家好，找創(chuàng)新互聯(lián)！從網(wǎng)頁設計、網(wǎng)站建設、微信開發(fā)、APP開發(fā)、成都響應式網(wǎng)站建設公司等網(wǎng)站項目制作，到程序開發(fā)，運營維護。創(chuàng)新互聯(lián)從2013年成立到現(xiàn)在10年的時間，我們擁有了豐富的建站經(jīng)驗和運維經(jīng)驗，來保證我們的工作的順利進行。專注于網(wǎng)站建設就選創(chuàng)新互聯(lián)。

注意：smart-doc已經(jīng)被開源中國收錄，并且開始被國內很多開發(fā)者使用到自己項目中快速生成接口文檔。

smart-doc功能

• 零注解、零學習成本、只需要寫標準java注釋。
• 基于源代碼接口定義自動推導，強大的返回結構推導。
• 支持Spring MVC,Spring Boot,Spring Boot Web Flux(controller書寫方式)。
• 支持Callable,Future,CompletableFuture等異步接口返回的推導。
• 支持JavaBean上的JSR303參數(shù)校驗規(guī)范。
• 對json請求參數(shù)的接口能夠自動生成模擬json參數(shù)。
• 對一些常用字段定義能夠生成有效的模擬值。
• 支持生成json返回值示例。
• 支持從項目外部加載源代碼來生成字段注釋(包括標準規(guī)范發(fā)布的jar包)。
• 支持生成多種格式文檔：Markdown、HTML5、Asciidoctor。
• 輕易實現(xiàn)在Spring Boot服務上在線查看靜態(tài)HTML5 api文檔。
• 開放文檔數(shù)據(jù)，可自由實現(xiàn)接入文檔管理系統(tǒng)。

  在Spring Boot項目中集成Smart-doc

  添加smart-doc依賴，注意打包后不需要將smart-doc打入最終的產(chǎn)品包，因此我推薦只用test級別就可以了。

    com.github.shalousun
    smart-doc
    [倉庫最新版]
    test

新建一個對象：

public class User {

    /**
     * 用戶名
     */
    private String userName;

    /**
     * 昵稱
     */
    private String nickName;

    /**
     * 用戶地址
     */
    private String userAddress;

    /**
     * 用戶年齡
     */
    private int userAge;

    /**
     * 手機號
     */
    private String phone;

    /**
     * 創(chuàng)建時間
     */
    private Long createTime;

    /**
     * ipv6
     */
    private String ipv6;

    /**
     * 固定電話
     */
    private String telephone;
    //省略get set
}

下面來新建一個UserController，然后將User作為Controller的請求參數(shù)和響應實體測試下smart-doc是如何輕松完成文檔生成的。

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

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

添加完成controller后，我們在項目中新建一個單元測試類用于跑文檔。

public class ApiDocTest {

    /**
     * 包括設置請求頭，缺失注釋的字段批量在文檔生成期使用定義好的注釋
     */
    @Test
    public void testBuilderControllersApi() {
        ApiConfig config = new ApiConfig();
        config.setServerUrl("http://localhost:8080");
        //true會嚴格要求注釋，推薦設置true
        config.setStrict(true);
        //true會將文檔合并導出到一個markdown
        //config.setAllInOne(true);
        //生成html時加密文檔名不暴露controller的名稱
        config.setMd5EncryptedHtmlName(true);

        //指定文檔輸出路徑
        //@since 1.7 版本開始，選擇生成靜態(tài)html doc文檔可使用該路徑：DocGlobalConstants.HTML_DOC_OUT_PATH;
        config.setOutPath("d:\\md");
        // @since 1.2,如果不配置該選項，則默認匹配全部的controller,
        // 如果需要配置有多個controller可以使用逗號隔開
        config.setPackageFilters("com.power.doc.controller");

        long start = System.currentTimeMillis();
        //獲取接口數(shù)據(jù)后自行處理
        ApiDocBuilder.builderControllersApi(config);
        long end = System.currentTimeMillis();
        DateTimeUtil.printRunTime(end, start);
    }
}

最后運行一下單元測試smart-doc即可生成markdown接口文檔到指定的目錄。

文檔生成效果

用戶信息操作接口

添加用戶

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

Type:POST

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

Request-parameters:

Request-example:

{
    "userName":"鵬飛.賀",
    "nickName":"raymond.gutkowski",
    "userAddress":"Apt. 819 蕭旁7699號， 章丘， 滇 852063",
    "userAge":41,
    "phone":"15018373016",
    "createTime":1569934393095,
    "ipv6":"9eb3:fada:ffd2:912e:6225:1062:a2d7:718f",
    "telephone":"15018373016"
}

Response-fields:

Response-example:

{
    "userName":"鵬飛.賀",
    "nickName":"raymond.gutkowski",
    "userAddress":"Apt. 819 蕭旁7699號， 章丘， 滇 852063",
    "userAge":41,
    "phone":"15018373016",
    "createTime":1569934393095,
    "ipv6":"9eb3:fada:ffd2:912e:6225:1062:a2d7:718f",
    "telephone":"15018373016"
}

是不是比swagger簡單很多呢，而且還完全不侵入代碼，只需要寫上標準的java doc注釋。需要了解更多多情況請查看smart-doc項目，好用請記得點star哦。查看smart-doc項目

注意:本文來自smart-doc原作者，您可以轉載但請勿copy充當原創(chuàng)。