色哟哟视频在线观看-色哟哟视频在线-色哟哟欧美15最新在线-色哟哟免费在线观看-国产l精品国产亚洲区在线观看-国产l精品国产亚洲区久久

0
  • 聊天消息
  • 系統消息
  • 評論與回復
登錄后你可以
  • 下載海量資料
  • 學習在線課程
  • 觀看技術視頻
  • 寫文章/發帖/加入社區
會員中心
創作中心

完善資料讓更多小伙伴認識你,還能領取20積分哦,立即完善>

3天內不再提示

一個無需注解的SpringBoot API文檔生成神器

Android編程精選 ? 來源:TJ君 ? 2023-03-13 09:38 ? 次閱讀

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

編寫和維護API文檔這個事情,對于后端程序員來說,是一件惱人但又不得不做的事情,我們都不喜歡寫文檔,但除非項目前后端代碼都是自己寫的,否則API文檔將是前后端協作中一個不可或缺的溝通界面。

既然不可避免,那就想辦法弄個輪子吧。人生苦短,必須偷懶。

無圖無真相,生成文檔的效果如下:

babe629c-c13b-11ed-bfe3-dac502259ad0.png

功能特性

1、代碼即文檔

JApiDocs是通過直接解析SpringBoot的源碼語法來工作的,所以只要Controller的語法符合一定的代碼規范,有合理的注釋,就可以直接導出文檔。

2、支持導出HTML

便捷的導航和接口查看界面;可本地預覽,或者部署到HTTP服務器。推薦部署到服務器,方便前后端展開協作。

3、同步導出客戶端Model代碼

支持導出Android端的 JavaiOS端的 Object C Model代碼,減少前端程序員的重復編碼工作。

4、更多特性

支持接口搜索;支持不同版本和英文文檔;自定義擴展等。

簡潔的文檔

再好用的東西,如果沒有文檔說明,別人也無從入手。為了讓大家盡快上手,JApiDocs準備了一份極簡的文檔說明,確保你在幾分鐘就能用上JApiDocs。

花5分鐘不到就能認識一個提高工作效率的工具,讓你把更多的時間花在更加有價值的事情上,你確認不看一下嗎?

  • 倉庫地址:https://github.com/YeDaxia/JApiDocs
  • 中文文檔:https://japidocs.agilestudio.cn/#/zh-cn/

支持接口搜索;支持不同版本和英文文檔;自定義擴展等。

入門

支持JDK:1.8+

快速開始

第一步:添加依賴

maven:

<dependency>
<groupId>io.github.yedaxiagroupId>
<artifactId>japidocsartifactId>
<version>1.3version>
dependency>

gradle:

compile'io.github.yedaxia1.3'
第二步:配置參數

你可以在任意一個main入口運行下面的代碼:

DocsConfigconfig=newDocsConfig();
config.setProjectPath("yourspringbootprojectpath");//項目根目錄
config.setProjectName("ProjectName");//項目名稱
config.setApiVersion("V1.0");//聲明該API的版本
config.setDocsPath("yourapidocspath");//生成API文檔所在目錄
config.setAutoGenerate(Boolean.TRUE);//配置自動生成
Docs.buildHtmlDocs(config);//執行生成文檔

如果沒有意外,執行完上面的代碼后,你就可以在配置的目錄中看到生成的文檔了。

編碼規范

JApiDocs是通過解析Java源碼來實現的,要使得JApiDocs正確工作,需要你在項目中的Controller書寫遵循一定的編碼規范。

你可以結合源碼中 SpringDemo 這個模塊來對照理解。

1. 添加必要的代碼注釋

其中類注釋會對應到一級接口分組,你也可以通過@description來指定分組名稱;JApiDocs 會通過 @param 來尋找接口參數和進一步解析參數的內容。

/**
*用戶接口
*/
@RequestMapping("/api/user/")
@RestController
publicclassUserController{

/**
*用戶列表
*@paramlistForm
*/
@RequestMapping(path="list",method={RequestMethod.GET,RequestMethod.POST})
publicApiResult>list(UserListFormlistForm){
returnnull;
}

/**
*保存用戶
*@paramuserForm
*/
@PostMapping(path="save")
publicApiResultsaveUser(@RequestBodyUserFormuserForm){
returnnull;
}

/**
*刪除用戶
*@paramuserId用戶ID
*/
@PostMapping("delete")
publicApiResultdeleteUser(@RequestParamLonguserId){
returnnull;
}
}

如果提交的表單是 application/x-www-form-urlencoded 類型的key/value格式,你可以在 SpringBoot 端通過在 @param 參數后添加字段解釋或者在相關的JavaBean對象里面添加解釋:

//直接在java的@param注解中
@paramuserId用戶ID
//在FormBean對象中
publicclassUserListFormextendsPageForm{
privateIntegerstatus;//用戶狀態
privateStringname;//用戶名
}

這種格式對于到文檔中的參數描述將是表格的形式:

baf58cfe-c13b-11ed-bfe3-dac502259ad0.png

如果提交的表單是 application/json 類型的json數據格式,對應 SpringBoot 中的 @RequestBody 注解,在文檔中則是 json 格式顯示:

{
"id":"long//用戶ID",
"name":"string//用戶名",
"phone":"long//電話",
"avatar":"string//頭像",
"gender":"byte//性別"
}
2. 接口聲明返回對象

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

比如上面的saveUser接口:

/**
*保存用戶
*@paramuserForm
*/
@PostMapping(path="save")
publicApiResultsaveUser(@RequestBodyUserFormuserForm){
returnnull;
}

ApiResult表明了該接口返回的數據結構,經過JApiDocs處理后是這樣的:

{
"code":"int",
"errMsg":"string",
"data":{
"userId":"string//用戶id",
"userName":"string//用戶名",
"friends":[
{
"userId":"string//用戶id",
"userName":"string//用戶名"
}
],
"readBooks":[
{
"bookId":"long//圖書id",
"bookName":"string//圖書名稱"
}
],
"isFollow":"boolean//是否關注"
}
}

如果你不是通過返回對象的形式,你也可以通過JApiDocs提供的@ApiDoc注解來聲明返回類型,你可以參考@ApiDoc章節的相關配置內容。

3. 接口對象在源碼中

我們知道,經過編譯后的 class 字節碼中是沒有注釋信息的,如果要通過反射字節碼的方式來實現,則不可避免要引入運行時注解,這樣會增加使用成本, 考慮到這一點,JApiDocs 從第二個版本之后就改成了使用解析源碼的方式,而不是反射字節碼的思路來實現了,但這樣直接導致的缺陷就是:所有的 Form Bean (表單)對象和返回對象就必須在項目的源碼中,否則就無法解析了,如果你們項目的JavaBean對象是通過jar包的形式提供的, 那很遺憾,JApiDocs將無法支持。

高級配置

@ApiDoc

JApiDocs 默認只導出聲明了@ApiDoc的接口,我們前面通過設置 config.setAutoGenerate(Boolean.TRUE) 來解除了這個限制。

如果你不希望把所有的接口都導出,你可以把autoGenerate設置關閉,在相關Controller類或者接口方法上通過添加@ApiDoc來確定哪些接口需要導出。

@ApiDoc聲明在接口方法上的時候,它還擁有一些更靈活的設置,下面我們來看一下:

  • result: 這個可以直接聲明返回的對象類型,如果你聲明了,將會覆蓋SpringBoot的返回對象
  • url: 請求URL,擴展字段,用于支持非SpringBoot項目
  • method: 請求方法,擴展字段,用于支持非SpringBoot項目

例子:

@ApiDoc(result=AdminVO.class,url="/api/v1/admin/login2",method="post")
@Ignore

如果你不想導出對象里面的某個字段,可以給這個字段加上@Ignore注解,這樣JApiDocs導出文檔的時候就會自動忽略掉了:

例子:

publicclassUserForm{
@Ignore
privateBytegender;//性別
}

自定義代碼模板

JApiDocs 除了支持文檔導出,目前也支持生成了 Android 和 iOS 的返回對象代碼,對應 Java 和 Object-C 語言, 如果你想修改代碼模板,可以通過以下的方法:

第一步:定義代碼模板

把源碼中library項目resources目錄下的代碼模板拷貝一份,其中,IOS_表示 Object-C 代碼模板,JAVA_開頭表示 Java代碼, 模板中類似${CLASS_NAME}的符號是替換變量,具體含義你可以結合生成的代碼進行理解,然后按照你想要的代碼模板進行修改即可。

第二步:選擇新的模板

通過DocsConfig配置模板路徑替換成新的模板:

docsConfig.setCodeTplPath("模板路徑");

添加更多功能

JApiDocs 提供了插件接口,你可以通過插件接口來實現更多豐富的功能,下面介紹如何添加插件:

第一步:實現 IPluginSupport 接口
publicclassCustomPluginimplementsIPluginSupport{

@Override
publicvoidexecute(ListcontrollerNodeList){
//實現你自己的功能需求
}
}
第二步:添加插件
config.addPlugin(newCustomPlugin());
審核編輯 :李倩
聲明:本文內容及配圖由入駐作者撰寫或者入駐合作網站授權轉載。文章觀點僅代表作者本人,不代表電子發燒友網立場。文章及其配圖僅供工程師學習之用,如有內容侵權或者其他違規問題,請聯系本站處理。 舉報投訴
  • API
    API
    +關注

    關注

    2

    文章

    1499

    瀏覽量

    61965
  • HTML
    +關注

    關注

    0

    文章

    278

    瀏覽量

    35214
  • 源碼
    +關注

    關注

    8

    文章

    639

    瀏覽量

    29185
  • SpringBoot
    +關注

    關注

    0

    文章

    173

    瀏覽量

    177

原文標題:一個無需注解的 SpringBoot API文檔生成神器,相當哇塞!

文章出處:【微信號:AndroidPush,微信公眾號:Android編程精選】歡迎添加關注!文章轉載請注明出處。

收藏 人收藏

    評論

    相關推薦

    如何使用SpringBoot集成Netty開發基于WebSocket的聊天室說明

    文檔的主要內容詳細介紹的是基于SpringBoot,借助Netty控制長鏈接,使用WebSocket協議做一個實時的聊天室。
    發表于 05-29 17:56 ?1次下載
    如何使用<b class='flag-5'>SpringBoot</b>集成Netty開發<b class='flag-5'>一</b><b class='flag-5'>個</b>基于WebSocket的聊天室說明

    Spring Boot的注解原理是什么

    @SpringBootApplication來看,發現@SpringBootApplication是組合注解。 @Target(ElementType.TYPE) @Retention
    的頭像 發表于 08-27 09:24 ?2192次閱讀

    文檔生成工具:Doxygen生成

    有了配置文件后我們完全可以通過命令行來生成API文檔,假設配置文件名為Doxyfile,那么我們只需要執行doxygen /path/to/Doxyfile即可生成
    的頭像 發表于 04-27 09:15 ?2363次閱讀

    如何設計優雅的API接口

    種是API接口提供方給出AK/SK兩值,雙方約定用SK作為簽名中的密鑰。AK接口調用方作為header中的accessKey傳遞給API接口提供方,這樣
    的頭像 發表于 12-20 14:23 ?1616次閱讀

    SpringBoot定時任務動態管理通用解決方案

    SpringBoot的定時任務的加強工具,實現對SpringBoot原生的定時任務進行動態管理,完全兼容原生@Scheduled注解,無需對原本的定時任務進行修改
    的頭像 發表于 02-03 09:49 ?774次閱讀

    什么是 SpringBoot

    本文從為什么要有 `SpringBoot`,以及 `SpringBoot` 到底方便在哪里開始入手,逐步分析了 `SpringBoot` 自動裝配的原理,最后手寫了
    的頭像 發表于 04-07 11:28 ?1306次閱讀
    什么是 <b class='flag-5'>SpringBoot</b>?

    SpringBoot常用注解及使用方法1

    基于 SpringBoot 平臺開發的項目數不勝數,與常規的基于`Spring`開發的項目最大的不同之處,SpringBoot 里面提供了大量的注解用于快速開發,而且非常簡單,基本可以做到開箱即用! 那
    的頭像 發表于 04-07 11:51 ?698次閱讀

    SpringBoot常用注解及使用方法2

    基于 SpringBoot 平臺開發的項目數不勝數,與常規的基于Spring開發的項目最大的不同之處,SpringBoot 里面提供了大量的注解用于快速開發,而且非常簡單,基本可以做到開箱即用!
    的頭像 發表于 04-07 11:52 ?675次閱讀

    Springboot常用注解合集

    前幾章,在系統啟動類里面,都加入了此啟動注解,此注解組合注解,包括了`@SpringBootConfiguration`、`@EnableAutoConfiguration`和`@
    的頭像 發表于 04-07 14:27 ?733次閱讀
    <b class='flag-5'>Springboot</b>常用<b class='flag-5'>注解</b>合集

    SpringBoot常用注解及原理

    SpringBootConfiguration繼承自@Configuration,二者功能也致,標注當前類是配置類, 并會將當前類內聲明的或多個以@Bean注解標記的方法的實例納
    的頭像 發表于 04-07 14:30 ?582次閱讀

    SpringBoot的核心注解1

    今天跟大家來探討下SpringBoot的核心注解@SpringBootApplication以及run方法,理解下springBoot為什么不需要XML,達到零配置
    的頭像 發表于 04-07 14:34 ?701次閱讀
    <b class='flag-5'>SpringBoot</b>的核心<b class='flag-5'>注解</b>1

    SpringBoot的核心注解2

    今天跟大家來探討下SpringBoot的核心注解@SpringBootApplication以及run方法,理解下springBoot為什么不需要XML,達到零配置
    的頭像 發表于 04-07 14:34 ?1958次閱讀
    <b class='flag-5'>SpringBoot</b>的核心<b class='flag-5'>注解</b>2

    springboot核心注解

    Spring Boot 是基于 Spring 框架的開源框架,它可以幫助開發者快速構建、部署和運行獨立的、生產級的 Spring 應用程序。Spring Boot 提供了系列核心注解,這些注解可以
    的頭像 發表于 11-23 09:23 ?513次閱讀

    注解搞定SpringBoot接口防刷

    技術要點:springboot的基本知識,redis基本操作,
    的頭像 發表于 11-28 10:46 ?402次閱讀

    SpringBoot核心注解由幾個注解組成

    等。本文將詳盡介紹這些核心注解。 @SpringBootApplication @SpringBootApplication 是復合注解,包含了 @Configuration、@
    的頭像 發表于 12-03 15:09 ?755次閱讀
    主站蜘蛛池模板: 我与旗袍老师疯狂床震| 久久国产热视频99rev6| 成人a视频在线观看| 91久久偷偷做嫩草影院免| 野花4在线观看| 午夜免费福利片| 色欲久久99精品久久久久久AV| 欧美激情精品久久久久| 蜜柚免费视频高清观看在线| 考试考90就可以晚上和老师C| 九九热精品免费观看| 交换:年轻夫妇-HD中文字幕| 狠狠啪在线香蕉| 狠狠啪在线香蕉| 久久精品久精品99热| 久久伊人影院| 美女gif趴跪式动态图| 蜜芽tv在线观看免费网站| 欧美 另类 美腿 亚洲 无码 | 永久adc视频年龄确认| 亚洲天堂2017无码| 真实国产熟睡乱子伦对白无套| 依人在线观看| 99久久久免费精品免费| PORN白嫩内射合集| 第一次破女初国产美女| 国产精品伊人| 黄色a三级免费看| 理论937| 欧美日本韩国一二区视频| 色多多旧版污污破解版| 午夜免费国产体验区免费的| 亚洲欧洲日产国码久在线| 中文字幕在线永久| yellow视频免费观看高清在线| 国产99久久久欧美黑人刘玥 | 91夫妻交友论坛| ppypp午夜限制不卡影院私人| XXX欧美性兽交| 成人免费视频在线观看| 国产99视频精品一区|