今天給大家安利一款接口文檔生成器——JApiDocs。

Swagger想必大家都用過吧，非常方便，功能也十分強(qiáng)大。如果非要說Swaager有什么缺點(diǎn)，想必就是注解寫起來比較麻煩。如果我說有一款不用寫注解，就可以生成文檔的工具，你心動(dòng)了嗎？他就是我們今天的主角——JApiDocs。

下面我們一起來看看如何使用！

一、添加依賴

<dependency><groupId>io.github.yedaxia</groupId><artifactId>japidocs</artifactId><version>1.3</version> </dependency>

二、配置生成參數(shù)

我們新建一個(gè)項(xiàng)目，然后隨便寫一個(gè)main方法，增加生成文檔的配置，然后運(yùn)行main方法。

DocsConfig?config?=?new?DocsConfig(); config.setProjectPath("F:\\Java旅途\\japi-docs");?//?項(xiàng)目根目錄 config.setProjectName("japi-docs");?//?項(xiàng)目名稱 config.setApiVersion("V1.0");???????//?聲明該API的版本 config.setDocsPath("F:\\test");?//?生成API?文檔所在目錄 config.setAutoGenerate(Boolean.TRUE);??//?配置自動(dòng)生成 Docs.buildHtmlDocs(config);?//?執(zhí)行生成文檔

三、編碼規(guī)范

由于JApiDocs是通過解析Java源碼來實(shí)現(xiàn)的，因此如果要想實(shí)現(xiàn)想要的文檔，還是需要遵循一定的規(guī)范。

3.1 類注釋、方法注釋和屬性注釋

如果我們想生成類的注釋，我們可以直接在類上加注釋，也可以通過加@description來生成。

/***?用戶接口類*/ @RequestMapping("/api/user") @RestController public?class?UserController?{}/***?@author?Java旅途*?@Description?用戶接口類*?@Date?2020-06-15?21:46*/ @RequestMapping("/api/user") @RestController public?class?UserController?{}

如果我們想生成方法的注釋，只能直接加注釋，不能通過加@description來生成。

/***?查詢用戶*?@param?age?年齡*?@return?R<User> */ @GetMapping("/list") public?R<User>?list(@RequestParam?int?age){User?user?=?new?User("Java旅途",?18);return?R.ok(user); }

JApiDocs可以自動(dòng)生成實(shí)體類，關(guān)于實(shí)體類屬性的注釋有三種方式，生成的效果都是一樣的，如下：

/***?用戶名稱*/ private?String?name; /***?用戶年齡*/ private?int?age; //?用戶名稱 private?String?name; //?用戶年齡 private?int?age; private?String?name;//?用戶名稱 private?int?age;//?用戶年齡

他除了支持咱們常用的model外，還支持IOS的model生成效果如下：

3.2 請(qǐng)求參數(shù)

如果提交的表單是 application/x-www-form-urlencoded 類型的key/value格式，則我們通過@param注解來獲取參數(shù)，在參數(shù)后面添加注釋，示例如下：

/***?@param?age?年齡*/ @GetMapping("/list") public?R<User>?list(@RequestParam?int?age){User?user?=?new?User("Java旅途",?18);return?R.ok(user); }

生成的文檔效果如下：

請(qǐng)求參數(shù)

參數(shù)名類型必須描述

age	int	否	年齡

如果提交的表單是 application/json 類型的json數(shù)據(jù)格式，如下：

/***?@param?user*?@return*/ @PostMapping("/add") public?R<User>?add(@RequestBody?User?user){return?R.ok(user); }

生成的文檔效果如下：

請(qǐng)求參數(shù)

{"name":?"string?//用戶名稱","age":?"int?//用戶年齡" }

3.3 響應(yīng)結(jié)果

我們知道，如果Controller聲明了@RestController，SpringBoot會(huì)把返回的對(duì)象直接序列成Json數(shù)據(jù)格式返回給前端。JApiDocs也利用了這一特性來解析接口返回的結(jié)果，但由于JApiDocs是靜態(tài)解析源碼的，因此你要明確指出返回對(duì)象的類型信息，JApiDocs支持繼承、泛型、循環(huán)嵌套等復(fù)雜的類解析。

因此我們不需要再寫注釋，它會(huì)根據(jù)我們的返回結(jié)果進(jìn)行解析，效果如下：

返回結(jié)果：

{"code":?"int","msg":?"string","data":?{"name":?"string?//用戶名稱","age":?"int?//用戶年齡"} }

最終，我們生成的接口文檔，如下：

四、高級(jí)配置

4.1 @ApiDoc

如果你不希望把所有的接口都導(dǎo)出，我們可以在配置中設(shè)置config.setAutoGenerate(Boolean.FALSE);然后在想要生成的接口上添加@ApiDoc。

@ApiDoc有以下三個(gè)屬性：

• result: 這個(gè)可以直接聲明返回的對(duì)象類型，如果你聲明了，將會(huì)覆蓋SpringBoot的返回對(duì)象

• url: 請(qǐng)求URL，擴(kuò)展字段，用于支持非SpringBoot項(xiàng)目

• method: 請(qǐng)求方法，擴(kuò)展字段，用于支持非SpringBoot項(xiàng)目

@ApiDoc(result?=?User.class,?url?=?"/api/user/view",?method?=?"post")

4.2 @Ignore

如果你不想導(dǎo)出對(duì)象里面的某個(gè)字段，可以給這個(gè)字段加上@Ignore注解，這樣JApiDocs導(dǎo)出文檔的時(shí)候就會(huì)自動(dòng)忽略掉了。

public?class?User?{@Ignoreprivate?int?age; }

五、總結(jié)

JApiDocs就介紹到這里了，優(yōu)勢(shì)劣勢(shì)大家很容易就看出來了。幾乎不需要注釋即可生成接口文檔，僅有的幾個(gè)注釋我們也可以通過ide來自動(dòng)生成。但是JApiDocs不具備Swagger在線調(diào)試功能。如果有一天JApiDocs支持在線調(diào)試后，那時(shí)候肯定會(huì)有一大波追隨者，畢竟寫代碼的誰喜歡寫多余的注解！

原創(chuàng)電子書

歷時(shí)整整一年總結(jié)的?Java 面試 + Java 后端技術(shù)學(xué)習(xí)指南，這是本人這幾年及校招的總結(jié)，各種高頻面試題已經(jīng)全部進(jìn)行總結(jié)，按照章節(jié)復(fù)習(xí)即可，已經(jīng)拿到了大廠offer。

原創(chuàng)思維導(dǎo)圖

掃碼或者微信搜?程序員的技術(shù)圈子?回復(fù)?面試?領(lǐng)取原創(chuàng)電子書和思維導(dǎo)圖。

總結(jié)

以上是生活随笔為你收集整理的你还在用 Swagger？试试这个神器！的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。