前言

大家好，我叫葉大俠，一名獨(dú)立開發(fā)者。這個(gè)文檔工具是我17年的一個(gè)想法，當(dāng)時(shí)還是在公司里面上班，負(fù)責(zé)App客戶端的開發(fā)工作，當(dāng)時(shí)后端童鞋寫文檔的意愿比較低，總是要等他們開發(fā)完接口，然后才在微信上溝通接口細(xì)節(jié)，顯然這樣的效率很低，導(dǎo)致前端的童鞋總是差不多deadline的時(shí)候才猛加班。

后面我建議讓他們能不能先把接口設(shè)計(jì)好，這樣大家可以并行開發(fā)，但顯然會(huì)增加了他們不少工作量，于是不太樂意。在這樣的背景下，我就想能不能搞個(gè)工具來(lái)自動(dòng)生成這個(gè)文檔，并且盡可能不增加他們的工作量。

當(dāng)時(shí)組里面后端用的還是play框架，我調(diào)研了一下這個(gè)框架，結(jié)合java強(qiáng)類型的語(yǔ)言特性，有了基本的思路，于是私下花了差不多兩周的時(shí)間做了個(gè)很初級(jí)的版本，雖然簡(jiǎn)陋，但基本可以滿足對(duì)文檔的需求了。

這就是JApiDocs最初的想法來(lái)源。

后來(lái)覺得這個(gè)東西別人也許也會(huì)需要，后面我就把它整理出來(lái)開源了，并擴(kuò)展支持了SpringBoot、JFinal框架。

不久這個(gè)項(xiàng)目受到了開源中國(guó)的推薦，收獲了一波星星，后面還受邀到源創(chuàng)會(huì)去分享了一下，這算是這個(gè)項(xiàng)目的巔峰時(shí)刻了。

后來(lái)由于我出來(lái)創(chuàng)業(yè)，慢慢就沒時(shí)間打理這個(gè)項(xiàng)目了，關(guān)注度也慢慢下去了。

內(nèi)心始終有股遺憾，碼農(nóng)生涯如果沒有個(gè)像樣的開源產(chǎn)品，感覺不是很圓滿，所以我又回來(lái)繼續(xù)完善這個(gè)開源工具了，雖然不知道最終是否會(huì)得到大家認(rèn)可，但還是想去嘗試一下。

簡(jiǎn)介

編寫和維護(hù)API文檔這個(gè)事情，對(duì)于后端程序員來(lái)說(shuō)，是一件惱人但又不得不做的事情，我們都不喜歡寫文檔，但除非項(xiàng)目前后端代碼都是自己寫的，否則API文檔將是前后端協(xié)作中一個(gè)不可或缺的溝通界面。

JApiDocs是一個(gè)無(wú)需額外注解、開箱即用的SpringBoot接口文檔生成工具。

無(wú)圖無(wú)真相，生成文檔的效果如下：

相比Swagger要寫一堆注解，Spring Rest Docs需要寫測(cè)試用例，才能生成API文檔，JApiDocs 具有無(wú)痛集成的特點(diǎn)。

快速開始

要使得JApiDcos正確工作，你寫的代碼應(yīng)該是像下面的樣子的：

/**
?*?用戶接口
?*/
@RequestMapping("/api/user/")
@RestController
public?class?UserController?{
????/**
?????*?用戶列表
?????*?@param?listForm
?????*/
????@RequestMapping(path?=?"list",?method?=?{RequestMethod.GET,??RequestMethod.POST}??)
????public?ApiResult>?list(UserListForm?listForm){return?null;
????}/**
?????*?保存用戶
?????*?@param?userForm
?????*/@PostMapping(path?=?"save")public?ApiResult?saveUser(@RequestBody?UserForm?userForm){return?null;
????}
}

我們給Controller類和方法加上必要的注釋，給接口方法返回相關(guān)的對(duì)象類型。是的，這樣JApiDocs就能解析到相關(guān)的接口信息了，就跟我們平時(shí)寫的代碼是差不多的，但要注意，你要通過(guò)@param來(lái)告訴JApiDocs接口的參數(shù)，但在IDE的幫助下，這個(gè)工作將是輕松愉悅的：

然后你在任意一個(gè)main入口方法執(zhí)行下面的代碼就可以生成文檔了：

DocsConfig?config?=?new?DocsConfig();
config.setProjectPath("your?springboot?project?path");?//?項(xiàng)目根目錄
config.setProjectName("ProjectName");?//?項(xiàng)目名稱
config.setApiVersion("V1.0");???????//?聲明該API的版本
config.setDocsPath("your?api?docs?path");?//?生成API?文檔所在目錄
config.setAutoGenerate(Boolean.TRUE);??//?配置自動(dòng)生成
Docs.buildHtmlDocs(config);?//?執(zhí)行生成文檔

接下來(lái)你只管好好寫代碼，生成Api文檔的工作就可以交給JApiDocs了，你不需要再為額外編寫和維護(hù)文檔而煩惱。

功能特性

1、代碼即文檔

JApiDocs是通過(guò)直接解析SpringBoot的源碼語(yǔ)法來(lái)工作的，所以只要Controller的語(yǔ)法符合一定的代碼規(guī)范，有合理的注釋，就可以直接導(dǎo)出文檔。

2、支持導(dǎo)出HTML

便捷的導(dǎo)航和接口查看界面；可本地預(yù)覽，或者部署到HTTP服務(wù)器。推薦部署到服務(wù)器，方便前后端展開協(xié)作。

3、同步導(dǎo)出客戶端Model代碼

支持導(dǎo)出Android端的 Java 和iOS端的 Object C Model代碼，減少前端程序員的重復(fù)編碼工作。

4、更多特性

支持接口搜索；支持不同版本和英文文檔；自定義擴(kuò)展等。

簡(jiǎn)潔的文檔

再好用的東西，如果沒有文檔說(shuō)明，別人也無(wú)從入手。為了讓大家盡快上手，JApiDocs準(zhǔn)備了一份極簡(jiǎn)的文檔說(shuō)明，確保你在幾分鐘就能用上JApiDocs。

人生苦短，必須偷懶。

花5分鐘不到就能認(rèn)識(shí)一個(gè)提高工作效率的工具，讓你把更多的時(shí)間花在更加有價(jià)值的事情上，你確認(rèn)不看一下嗎？

https://github.com/YeDaxia/JApiDocs?(可點(diǎn)擊文章最下面的原文鏈接到項(xiàng)目主頁(yè))

溫馨提示：GitHub上收藏和支持一個(gè)項(xiàng)目最好的方式就是點(diǎn)個(gè)star哦！

接下來(lái)的計(jì)劃

這個(gè)工具的目標(biāo)很明確，就是盡可能提升前后端溝通和開發(fā)效率。接下來(lái)的計(jì)劃包括但不限于：

支持更多導(dǎo)出文檔格式；

自動(dòng)生成前端的接口代碼，供App或網(wǎng)頁(yè)前端開發(fā)同學(xué)直接使用；

把發(fā)生變化的接口標(biāo)識(shí)出來(lái)；

對(duì)接一些開源mock平臺(tái)等。

開源不易，歡迎大家關(guān)注和支持！

關(guān)于AgileStudio

我們是一支由資深獨(dú)立開發(fā)者和設(shè)計(jì)師組成的團(tuán)隊(duì)，成員均有扎實(shí)的技術(shù)實(shí)力和多年的產(chǎn)品設(shè)計(jì)開發(fā)經(jīng)驗(yàn)，提供可信賴的軟件定制服務(wù)。

總結(jié)

以上是生活随笔為你收集整理的itextpdf api帮助文档_我开源了一个小工具，可以帮你轻松生成 SpringBoot API 文档...的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問題。

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