优于 swagger 的 java markdown 文档自动生成框架-01-入门使用

设计初衷

节约时间

Java 文档一直是一个大问题。

不少项目不写文档，即便写文档，对于开发人员来讲也是很是痛苦的。

不写文档的缺点自不用多少，手动写文档的缺点也显而易见：

1. 很是浪费时间，并且会出错。

2. 没法保证及时更新。代码已经变了，可是文档还要同步修改。须要强制人来维护这一种一致性。这很难。

为何不是 swagger-ui

java 的文档有几类：

1. jdk 自带的 doc 生成。这个之前实践给别人用过，别人用 C#，看到 java 的默认文档感受很痛苦。

就算是咱们 java 开发者，也很讨厌看 jdk 的文档。看着不美观，也很累。

2. swagger-ui 是基于 java 注解的文档生成工具。相对而言比较优雅，也很是强大。

可是缺点也是有的。开发人员要写 jdk 原来的注释+注解。注解太多，致使写起来也很痛苦，大部分开发者后来仍是选择了放弃。

那么问题来了？咱们怎么办才能尽量的让开发人员，和文档阅读人员都乐于接受呢？

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

区别以下：

1. 尽量的保证和 Java 原生注释一致，让开发者很容易就可使用。

2. 尽量的信息全面，可是文档简洁。让文档的阅读者享受到等同于手写文档的体验。

3. 将信息的获取和生成区分开。方便用户本身定义本身的输出方式。

IDOC

i-doc 项目简介

为 java 项目生成项目文档。

基于原生的 java 注释，尽量的生成简介的文档。用户能够自定义本身的模板，生成本身须要的文档。

特性

• 基于 maven 项目生成包含大部分信息的元数据

• 默认支持 markdown 简化文档的生成，支持自定义模板

• 支持用户自定义文档生成器

• 支持用户自定生成文档的类过滤器

新特性

• 添加字段类型别名，支持用户自定义

快速入门

须要

jdk1.8+

maven 3.x+

maven 引入

使用 maven 引入当前 idoc 插件。

<build>
    <plugins>
        <plugin>
            <groupId>com.github.houbb</groupId>
            <artifactId>idoc-core</artifactId>
            <version>0.1.0</version>
        </plugin>
    </plugins>
</build>
复制代码

测试对象的建立

为了演示文档，咱们建立了一个 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;
    }
}

复制代码

执行插件

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-插件的参数配置

03-自定义生成文件过滤器

04-字段类型别名支持

开源地址

idoc