將JavaDoc註釋生成API文檔的操作

Posted on 2021-11-24 by WalkonNet

將JavaDoc 註釋生成API文檔

1. 打開java代碼，編寫JavaDoc 註釋，隻有按照java的規范編寫註釋，才能很好的生成API文檔，javadoc註釋與普通註釋的區別為多一個*（星號）。普通代碼註釋為/*XXX*/，而javadoc的註釋為/**XXX*/

2. javadoc註釋要盡量寫的詳細，這樣別人在沒有源碼的情況下才知道如

何使用您的代碼。

3. 點擊eclipse的【Project】菜單，選擇【Generate JavaDoc】選項。

（1）選擇您要生成JavaDoc的工程

（2）選擇哪些級別的內容生成JavaDoc，默認為public，如果選擇private則會全部內容都生成。

（3）選擇doc的生成位置，默認為工程目錄下，建議不要修改。

（4）點擊【Next】按鈕

（1）勾選Document Title，然後填寫文檔標題。

（2）點擊【Next】按鈕

（1）選擇使用的jdk版本（看自己的版本是多少就選擇多少）

（2）點擊【Finish】按鈕

7. 可以看到控制臺輸出生成javadoc的信息。

8. 項目下生成一個【doc】的目錄，裡面存放著javadoc文檔。

9. 打開doc目錄，用瀏覽器打開index.html

10. 可以看到一個完整的API文檔、javadoc就生成瞭。

java自動api文檔生成Yapi

開發過程中，接口文檔是前後端，測試交互的依據，文檔更新的及時性和準確性很重要。

word文檔缺點

手動編寫，出錯性很高
文檔可讀性差，考驗編寫者的耐心
無法在線調試
及時性差

swwager文檔缺點

文檔可讀性差
針對需要帶授權token的請求，無法在線調試
無法導入和導出api文檔
測試和開發無法在文檔上溝通

Yapi解決以上所有問題，yapi可以支持java apidoc ,兼容swwager，隻需要idea安裝對應插件，就可以實現右鍵點擊upload to yapi，自動生成api接口文檔

    @ApiOperation("管理員創建用戶")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "header", name = "Authentication", dataType = "String", required = true, value = "用戶token")
    })
    @PostMapping("/users/user")
    public CommonResult<UserCreateResponse> createUser(@Validated @RequestBody UserAddRequest userAddRequest) {
        Assert.isTrue(userAddRequest != null, "invalid userAddRequest");
        return CommonResult.ok(userService.addUser(userAddRequest));
    }

在這裡插入圖片描述

Yapi使用，官方教程

以上為個人經驗，希望能給大傢一個參考，也希望大傢多多支持WalkonNet。

將JavaDoc註釋生成API文檔的操作

目錄