設(shè)計(jì)初衷

節(jié)約時(shí)間

Java 文檔一直是一個(gè)大問(wèn)題。

創(chuàng)新互聯(lián)建站網(wǎng)站建設(shè)由有經(jīng)驗(yàn)的網(wǎng)站設(shè)計(jì)師、開(kāi)發(fā)人員和項(xiàng)目經(jīng)理組成的專(zhuān)業(yè)建站團(tuán)隊(duì)，負(fù)責(zé)網(wǎng)站視覺(jué)設(shè)計(jì)、用戶體驗(yàn)優(yōu)化、交互設(shè)計(jì)和前端開(kāi)發(fā)等方面的工作，以確保網(wǎng)站外觀精美、網(wǎng)站建設(shè)、網(wǎng)站設(shè)計(jì)易于使用并且具有良好的響應(yīng)性。

很多項(xiàng)目不寫(xiě)文檔，即使寫(xiě)文檔，對(duì)于開(kāi)發(fā)人員來(lái)說(shuō)也是非常痛苦的。

不寫(xiě)文檔的缺點(diǎn)自不用多少，手動(dòng)寫(xiě)文檔的缺點(diǎn)也顯而易見(jiàn)：

1. 非常浪費(fèi)時(shí)間，而且會(huì)出錯(cuò)。

2. 無(wú)法保證及時(shí)更新。代碼已經(jīng)變了，但是文檔還要同步修改。需要強(qiáng)制人來(lái)維護(hù)這一種一致性。這很難。

為什么不是 swagger-ui

java 的文檔有幾類(lèi)：

1. jdk 自帶的 doc 生成。這個(gè)以前實(shí)踐給別人用過(guò)，別人用 C#，看到 java 的默認(rèn)文檔感覺(jué)很痛苦。

就算是我們 java 開(kāi)發(fā)者，也很討厭看 jdk 的文檔。看著不美觀，也很累。

2. swagger-ui 是基于 java 注解的文檔生成工具。相對(duì)而言比較優(yōu)雅，也非常強(qiáng)大。

但是缺點(diǎn)也是有的。開(kāi)發(fā)人員要寫(xiě) jdk 原來(lái)的注釋+注解。注解太多，導(dǎo)致寫(xiě)起來(lái)也很痛苦，大部分開(kāi)發(fā)者后來(lái)還是選擇了放棄。

那么問(wèn)題來(lái)了？我們?cè)趺崔k才能盡可能的讓開(kāi)發(fā)人員，和文檔閱讀人員都樂(lè)于接受呢？

jdk 自帶的 doc 就是基于 maven 插件的，本項(xiàng)目也是。

區(qū)別如下：

1. 盡可能的保證和 Java 原生注釋一致，讓開(kāi)發(fā)者很容易就可以使用。

2. 盡可能的信息全面，但是文檔簡(jiǎn)潔。讓文檔的閱讀者享受到等同于手寫(xiě)文檔的體驗(yàn)。

3. 將信息的獲取和生成區(qū)分開(kāi)。方便用戶自己定義自己的輸出方式。

IDOC

i-doc 項(xiàng)目簡(jiǎn)介

為 java 項(xiàng)目生成項(xiàng)目文檔。

基于原生的 java 注釋?zhuān)M可能的生成簡(jiǎn)介的文檔。用戶可以自定義自己的模板，生成自己需要的文檔。

特性

• 基于 maven 項(xiàng)目生成包含大部分信息的元數(shù)據(jù)

• 默認(rèn)支持 markdown 簡(jiǎn)化文檔的生成，支持自定義模板

• 支持用戶自定義文檔生成器

• 支持用戶自定生成文檔的類(lèi)過(guò)濾器

新特性

• 添加字段類(lèi)型別名，支持用戶自定義

快速入門(mén)

需要

jdk1.8+

maven 3.x+

maven 引入

使用 maven 引入當(dāng)前 idoc 插件。

    
        
            com.github.houbb
            idoc-core
            0.1.0
        
    

測(cè)試對(duì)象的創(chuàng)建

為了演示文檔，我們創(chuàng)建了一個(gè) Address 對(duì)象。

package com.github.houbb.idoc.test.model;

/**
 * 地址
 * @author binbin.hou
 * @since 0.0.1
 */
public class Address {

    /**
     * 城市
     */
    private String country;

    /**
     * 街道
     */
    private String street;

    public String getCountry() {
        return country;
    }

    public void setCountry(String country) {
        this.country = country;
    }

    public String getStreet() {
        return street;
    }

    public void setStreet(String street) {
        this.street = street;
    }
}

執(zhí)行插件

mvn com.github.houbb:idoc-core:0.0.2:idoc

命令行日志信息

[INFO] ------------------------------------ Start generate doc
[INFO] 共計(jì) 【1】 個(gè)文件待處理，請(qǐng)耐心等待。進(jìn)度如下：
==================================================================================================== 100%
[INFO] Generator doc with docGenerator: com.github.houbb.idoc.core.api.generator.ConsoleDocGenerator
[INFO] ------------------------------------ 文檔信息如下：

[類(lèi)名] com.github.houbb.idoc.test.model.Address
[類(lèi)信息] {"comment":"地址","docAnnotationList":[],"docFieldList":[{"comment":"城市","name":"country","type":"java.lang.String"},{"comment":"街道","name":"street","type":"java.lang.String"}],"docMethodList":[{"docMethodParameterList":[],"docMethodReturn":{"fullName":"java.lang.String","name":"String","packageName":"java.lang"},"docTagList":[],"exceptionList":[],"modifiers":["public"],"name":"getCountry","seeList":[],"signature":"getCountry()"},{"docMethodParameterList":[{"docAnnotationList":[],"name":"country","type":"java.lang.String"}],"docMethodReturn":{},"docTagList":[],"exceptionList":[],"modifiers":["public"],"name":"setCountry","seeList":[],"signature":"setCountry(country)"},{"docMethodParameterList":[],"docMethodReturn":{"fullName":"java.lang.String","name":"String","packageName":"java.lang"},"docTagList":[],"exceptionList":[],"modifiers":["public"],"name":"getStreet","seeList":[],"signature":"getStreet()"},{"docMethodParameterList":[{"docAnnotationList":[],"name":"street","type":"java.lang.String"}],"docMethodReturn":{},"docTagList":[],"exceptionList":[],"modifiers":["public"],"name":"setStreet","seeList":[],"signature":"setStreet(street)"}],"docTagList":[{"lineNum":5,"name":"author","parameters":["binbin.hou"],"value":"binbin.hou"},{"lineNum":6,"name":"since","parameters":["0.0.1"],"value":"0.0.1"}],"fullName":"com.github.houbb.idoc.test.model.Address","modifiers":["public"],"name":"Address","packageName":"com.github.houbb.idoc.test.model"}

[INFO] ------------------------------------ Finish generate doc

Markdown 的生成

參考 03-自定義生成文件過(guò)濾器

效果參見(jiàn) idoc-test-全部文檔.md

進(jìn)一步學(xué)習(xí)

00-項(xiàng)目概覽

01-設(shè)計(jì)初衷

02-插件的參數(shù)配置

03-自定義生成文件過(guò)濾器

04-字段類(lèi)型別名支持

開(kāi)源地址

idoc