Java文檔自動(dòng)生成

java-api-doc

勵(lì)志做java屆最好的文檔生成工具，自動(dòng)解析代碼生成api接口文檔，前后臺(tái)分離開發(fā)的福音，零代碼入侵，零注釋入侵
https://github.com/liupeng328/java-api-doc/tree/master?tdsourcetag=s_pctim_aiomsg
https://gitee.com/lovepeng/apidoc2

解決的痛點(diǎn)

通常的文檔生成工具，都需要開發(fā)人員編寫注解或注釋，代碼入侵太強(qiáng)，而且費(fèi)事，我希望工具自動(dòng)解析代碼，然后根據(jù)代碼生成文檔，如果有注釋就自動(dòng)掃描注釋，沒有就以代碼為準(zhǔn)，生成的文檔如果有不合理的地方，可以在頁面進(jìn)行修改，利用web頁面的表單編輯修改要比在代碼里處理方便直觀。

頁面布局

如下圖（圖片拼接左側(cè)菜單可能模糊或重影，湊合看）：


  1. 左側(cè)為菜單，菜單分為兩級(jí)，一級(jí)表示模塊，二級(jí)表示接口信息，一級(jí)菜單就是你定義的模塊名稱，二級(jí)菜單是對(duì)外接口的方法名，如果你的方法上有注釋，這里會(huì)自動(dòng)解析方法的注釋作為二級(jí)菜單。菜單拖拽可以排序。

  2. 右側(cè)為接口詳細(xì)信息，主要包括：模擬測試功能，接口詳細(xì)信息說明，請(qǐng)求參數(shù)說明，響應(yīng)參數(shù)說明，參數(shù)的詳細(xì)信息也是默認(rèn)解析代碼，如有注釋優(yōu)先展示注釋，支持對(duì)象的泛型，多維數(shù)組，自嵌套，互相嵌套，并根據(jù)參數(shù)信息生成一個(gè)演示的例子表明接口的使用方式

頁面操作

  1. 左側(cè)二級(jí)菜單可以雙擊修改，失去焦點(diǎn)時(shí)自動(dòng)保存
image.png
  1. 左側(cè)一級(jí)，二級(jí)菜單可以拖拽排序
  1. 所有帶 “編輯”按鈕的地方都可以編輯保存，textarea編輯時(shí)可以帶回車換行，自動(dòng)記錄你的文本格式

  1. 請(qǐng)求參數(shù)和響應(yīng)參數(shù)，本身是一個(gè)樹結(jié)構(gòu)，所有編輯的時(shí)候跟普通的編輯樹一樣操做，包括添加一級(jí)數(shù)據(jù)，添加子數(shù)據(jù)，修改，刪除，保存等等，鼠標(biāo)移入會(huì)有提示，如下圖

5.如果需要給接口提供默認(rèn)值，修改參數(shù)的默認(rèn)值后，會(huì)自動(dòng)重構(gòu)json參數(shù)，告訴你接口怎么使用，清晰明了

image.png
  1. 工具提供自動(dòng)化測試，支持默認(rèn)數(shù)據(jù)填充，前后臺(tái)都拋棄PostMan等第三方測試工具吧

代碼使用

  1. 引入jar包（暫未上傳maven，近期上傳maven）
       <!--Maven jar包引入方式-->
        <dependency>
            <groupId>com.apidoc</groupId>
            <artifactId>apidoc</artifactId>
            <version>1.0.0</version>
            <scope>system</scope>
            <systemPath>${project.basedir}/src/main/resources/lib/apidoc-1.0.0.jar</systemPath>
        </dependency>
    </dependencies>
  1. 修改配置文件
#是否開啟apidoc
apidoc=true

# datasource 數(shù)據(jù)源配置，目前僅支持mysql，如果需要其他數(shù)據(jù)庫，請(qǐng)自行修改com.apidoc.dao數(shù)據(jù)庫操作層的sql，或者聯(lián)系我修改（需要付費(fèi)）
spring.datasource.driver-class-name=com.mysql.jdbc.Driver
spring.datasource.url=jdbc:mysql://127.0.0.1:3306/apidoc?useUnicode=true&zeroDateTimeBehavior=convertToNull&autoReconnect=true&characterEncoding=UTF-8&characterSetResults=UTF-8&allowMultiQueries=true&&useSSL=false
spring.datasource.username=root
spring.datasource.password=root
  1. 增加springboot快速配置類
/**
 * 配置類
 * 讓springboot自動(dòng)掃描并管理apidoc工具下的所有class
 */
@Configuration
@EnableTransactionManagement//啟動(dòng)事務(wù)
@ComponentScan("com.apidoc")//掃描組件類
@MapperScan("com.apidoc.dao")//掃描數(shù)據(jù)庫操作層的類
@EntityScan("com.apidoc.entity")//掃描實(shí)體類
public class ApiDocConfig {
    @Bean
    public ApiDocService generator() {
        //所有的常量都在Const類下，需要修改常量的在這里配置即可
        //配置代碼的絕對(duì)路徑，方便掃描代碼的注釋，因?yàn)樽⑨尵幾g之后就被jvm剔除了，只能掃描源碼，不配置則不掃描注釋
        //默認(rèn)路徑為{項(xiàng)目路徑}+src/main/java
        Const.codePath = Const.projectPath + "apidoc-demo" + File.separator + "src" + File.separator + "main" + File.separator + "java" + File.separator;
        return new ApiDocService();
    }
}
  1. 在你的controller類上增加注解@Api("這里寫模塊名稱")，這里一個(gè)@Api對(duì)應(yīng)頁面的一個(gè)一級(jí)菜單，即模塊，模塊可以由多個(gè)類組成，只需設(shè)置每個(gè)類的模塊名稱一樣，程序會(huì)自動(dòng)把模塊名稱一樣的class組裝成同一模塊。
  2. 瀏覽器訪問地址http://localhost:8080/apidoc/index.html?packageName=com.demo即可。如果一個(gè)項(xiàng)目有多個(gè)文檔，比如前端頁面一個(gè)文檔，后臺(tái)管理一個(gè)文檔等等，可以用java的包區(qū)分。一個(gè)包代表一個(gè)文檔，不同的文檔使用不同的包即可。即url后的參數(shù)：packageName=你的包名

特別說明&&高級(jí)模式

目前僅支持SpringMVC/SpringBoot+Mybatis+MySQL技術(shù)架構(gòu)，如果您使用其他技術(shù)，可以下載我的源碼稍作修改，或聯(lián)系我修改（需要付費(fèi)）

工具是標(biāo)準(zhǔn)的前后臺(tái)分離開發(fā)架構(gòu)，后臺(tái)為MVC開發(fā)模式，如果你的技術(shù)跟我使用的不一樣選擇性替換相應(yīng)的代碼層即可。

  • 路由控制層：替換這一個(gè)類即可com.apidoc.controller.ApiDocController
  • 數(shù)據(jù)庫操作層：修改這個(gè)包的sql即可com.apidoc.dao
  • 頁面中所有的常量都可以配置，包括路由等等，具體見常量類com.apidoc.common.Const
  • 嫌棄前端頁面丑陋：apidoc/front這個(gè)路徑下是我的所有前端代碼，我才用的是最新版的angualr做的，你可以選擇你喜歡的任何前端技術(shù)重構(gòu)自己的頁面，然后對(duì)接后臺(tái)接口即可?？偣踩缦陆涌冢捎脴?biāo)準(zhǔn)的RESTful風(fēng)格
//api接口
export const apis={
  isOpenApiDoc:"/apidoc/isOpenApiDoc",
  info:"/apidoc/info",
  modules:"/apidoc/modules",
  actions:"/apidoc/actions",
  detail:"/apidoc/detail",
  updateInfo: "/apidoc/updateInfo",
  updateAction: "/apidoc/updateAction",
  updateActionDescription: "/apidoc/updateActionDescription",
  updateDetail: "/apidoc/updateDetail",
  updateModulesSort: "/apidoc/updateModulesSort",
  updateActionsSort: "/apidoc/updateActionsSort",
  addParam:"/apidoc/addParam",
  updateParam:"/apidoc/updateParam",
  deleteParam:"/apidoc/deleteParam",
};
最后編輯于 ：
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請(qǐng)聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時(shí)請(qǐng)結(jié)合常識(shí)與多方信息審慎甄別。
平臺(tái)聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點(diǎn)，簡書系信息發(fā)布平臺(tái)，僅提供信息存儲(chǔ)服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容