優(yōu)于 swagger 的 java markdown 文檔自動生成框架-01-入門使用

RdouTyping 發(fā)布于2019-08-16 15:53 / 1186人閱讀

摘要：很多項目不寫文檔，即使寫文檔，對于開發(fā)人員來說也是非常痛苦的。無法保證及時更新。是基于注解的文檔生成工具。讓文檔的閱讀者享受到等同于手寫文檔的體驗。將信息的獲取和生成區(qū)分開。基于原生的注釋，盡可能的生成簡介的文檔。

設計初衷 節(jié)約時間

Java 文檔一直是一個大問題。

很多項目不寫文檔，即使寫文檔，對于開發(fā)人員來說也是非常痛苦的。

不寫文檔的缺點自不用多少，手動寫文檔的缺點也顯而易見：

非常浪費時間，而且會出錯。

無法保證及時更新。代碼已經(jīng)變了，但是文檔還要同步修改。需要強制人來維護這一種一致性。這很難。

為什么不是 swagger-ui

java 的文檔有幾類：

jdk 自帶的 doc 生成。這個以前實踐給別人用過，別人用 C#，看到 java 的默認文檔感覺很痛苦。

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

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

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

那么問題來了？我們怎么辦才能盡可能的讓開發(fā)人員，和文檔閱讀人員都樂于接受呢？

jdk 自帶的 doc 就是基于 maven 插件的，本項目也是。

區(qū)別如下：

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

盡可能的信息全面，但是文檔簡潔。讓文檔的閱讀者享受到等同于手寫文檔的體驗。

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

IDOC i-doc 項目簡介

為 java 項目生成項目文檔。

基于原生的 java 注釋，盡可能的生成簡介的文檔。用戶可以自定義自己的模板，生成自己需要的文檔。

特性

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

默認支持 markdown 簡化文檔的生成，支持自定義模板

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

支持用戶自定生成文檔的類過濾器

新特性

添加字段類型別名，支持用戶自定義

快速入門 需要

jdk1.8+

maven 3.x+

maven 引入

使用 maven 引入當前 idoc 插件。


    
        
            com.github.houbb
            idoc-core
            0.1.0

測試對象的創(chuàng)建

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

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] 共計 【1】 個文件待處理，請耐心等待。進度如下：
==================================================================================================== 100%
[INFO] Generator doc with docGenerator: com.github.houbb.idoc.core.api.generator.ConsoleDocGenerator
[INFO] ------------------------------------ 文檔信息如下：

[類名] com.github.houbb.idoc.test.model.Address
[類信息] {"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-自定義生成文件過濾器

效果參見 idoc-test-全部文檔.md

進一步學習

00-項目概覽

01-設計初衷

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

03-自定義生成文件過濾器

04-字段類型別名支持

開源地址

idoc

云服務器 GPU云服務器 java框架入門使用java幫助文檔 java01++ java01算法

文章版權歸作者所有，未經(jīng)允許請勿轉(zhuǎn)載,若此文章存在違規(guī)行為，您可以聯(lián)系管理員刪除。

轉(zhuǎn)載請注明本文地址：http://specialneedsforspecialkids.com/yun/73761.html

【效率專精系列】善用API統(tǒng)一描述語言提升RestAPI開發(fā)效率

摘要：其標準為前身是，提供強大的在線編輯功能，包括語法高亮錯誤提示自動完成實時預覽，并且支持用戶以格式撰寫導入導出轉(zhuǎn)換文檔。團隊內(nèi)部RestAPI開發(fā)采用設計驅(qū)動開發(fā)的模式，即使用API設計文檔解耦前端和后端的開發(fā)過程，雙方只在聯(lián)調(diào)與測試時耦合。在實際開發(fā)和與前端合作的過程中，受限于眾多因素的影響，開發(fā)效率還有進一步提高的空間。本文的目的是優(yōu)化工具鏈支持，減少一部分重復和枯燥的勞動。現(xiàn)狀...

tianyu 2019-08-16 10:42 評論0 收藏0
api 接口管理工具

摘要：接口管理工具大致分為線上工具和自建工具。安裝其他工具上面講的，不管是線上工具還是自建工具，都是接口集成工具，主要是為了提供數(shù)據(jù)功能。類似網(wǎng)易云筆記印象筆記的筆記管理工具。 api 接口管理工具現(xiàn)在，Web 應用的前后端分離事實上已經(jīng)成為了大家都認可的一種開發(fā)方式，前后端分離之后，前端與后端都用接口（api）來溝通，這就需要我們做好 API 接口管理，所以，這次來聊聊 API 接口管理...

marser 2019-08-23 14:43 評論0 收藏0
api 接口管理工具

摘要：接口管理工具大致分為線上工具和自建工具。安裝其他工具上面講的，不管是線上工具還是自建工具，都是接口集成工具，主要是為了提供數(shù)據(jù)功能。類似網(wǎng)易云筆記印象筆記的筆記管理工具。 api 接口管理工具現(xiàn)在，Web 應用的前后端分離事實上已經(jīng)成為了大家都認可的一種開發(fā)方式，前后端分離之后，前端與后端都用接口（api）來溝通，這就需要我們做好 API 接口管理，所以，這次來聊聊 API 接口管理...

wuyumin 2019-08-16 14:27 評論0 收藏0
Wizard 開源文檔管理系統(tǒng)1.0發(fā)布啦

摘要：總結如果你在為公司尋找一款開源免費的開發(fā)文檔文檔管理工具，不妨考慮一下項目，一定不會讓你失望的。 Wizard 是一款開源文檔管理系統(tǒng)，項目地址為 https://github.com/mylxsw/wizard。這個項目是我在2017年就開始開發(fā)的，起初只是想做一款能夠在公司內(nèi)部把Swagger文檔管理起來的工具，但在這近兩年的時間里，一直斷斷續(xù)續(xù)的為其添加各種功能，現(xiàn)在終于下決...

cod7ce 2019-07-01 12:44 評論0 收藏0
微服務橫行的今天, 你的文檔跟上節(jié)奏了么?

摘要：納尼隔壁少林派表示自家金剛技壓群雄在座各位都是。。。納尼你覺得寫太繁瑣了你不喜歡我們還有或者等等一大堆工具呢。納尼沒有你還是覺得無法接受好吧那么筆者推薦類似這類更友好的工具你可以導入導出其他格式也可以使用其來撰寫。說起微服務, 想必現(xiàn)在的技術圈內(nèi)人士個個都能談笑風云, 娓娓道來。的確, 技術變革日新月異, 各種工具框架雨后春筍般涌現(xiàn), 現(xiàn)在我們可以輕巧便捷地根據(jù)自己的業(yè)務需求, 構建...

liaoyg8023 2019-08-14 16:55 評論0 收藏0