快捷導(dǎo)航

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

更新時(shí)間：2021年11月24日 16:13:11 作者：油紙

這篇文章主要介紹了將JavaDoc注釋生成API文檔的操作，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方，望不吝賜教

將JavaDoc 注釋生成API文檔

1. 打開java代碼，編寫JavaDoc 注釋，只有按照java的規(guī)范編寫注釋，才能很好的生成API文檔，javadoc注釋與普通注釋的區(qū)別為多一個(gè)*（星號(hào)）。普通代碼注釋為/*XXX*/，而javadoc的注釋為/**XXX*/

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

何使用您的代碼。

3. 點(diǎn)擊eclipse的【Project】菜單，選擇【Generate JavaDoc】選項(xiàng)。

4.

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

（2）選擇哪些級(jí)別的內(nèi)容生成JavaDoc，默認(rèn)為public，如果選擇private則會(huì)全部內(nèi)容都生成。

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

（4）點(diǎn)擊【Next】按鈕

5.

（1）勾選Document Title，然后填寫文檔標(biāo)題。

（2）點(diǎn)擊【Next】按鈕

6.

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

（2）點(diǎn)擊【Finish】按鈕

7. 可以看到控制臺(tái)輸出生成javadoc的信息。

8. 項(xiàng)目下生成一個(gè)【doc】的目錄，里面存放著javadoc文檔。

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

10. 可以看到一個(gè)完整的API文檔、javadoc就生成了。

java自動(dòng)api文檔生成Yapi

開發(fā)過程中，接口文檔是前后端，測試交互的依據(jù)，文檔更新的及時(shí)性和準(zhǔn)確性很重要。

word文檔缺點(diǎn)

手動(dòng)編寫，出錯(cuò)性很高
文檔可讀性差，考驗(yàn)編寫者的耐心
無法在線調(diào)試
及時(shí)性差

swwager文檔缺點(diǎn)

文檔可讀性差
針對(duì)需要帶授權(quán)token的請求，無法在線調(diào)試
無法導(dǎo)入和導(dǎo)出api文檔
測試和開發(fā)無法在文檔上溝通

Yapi解決以上所有問題，yapi可以支持java apidoc ,兼容swwager，只需要idea安裝對(duì)應(yīng)插件，就可以實(shí)現(xiàn)右鍵點(diǎn)擊upload to yapi，自動(dòng)生成api接口文檔

    @ApiOperation("管理員創(chuàng)建用戶")
    @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));
    }

在這里插入圖片描述