共计 3314 个字符，预计需要花费 9 分钟才能阅读完成。
设计初衷
节约时间
Java 文档一直是一个大问题。
很多项目不写文档，即使写文档，对于开发人员来说也是非常痛苦的。
不写文档的缺点自不用多少，手动写文档的缺点也显而易见：
非常浪费时间，而且会出错。
无法保证及时更新。代码已经变了，但是文档还要同步修改。需要强制人来维护这一种一致性。这很难。
为什么不是 swagger-ui
java 的文档有几类：
jdk 自带的 doc 生成。这个以前实践给别人用过，别人用 C#，看到 java 的默认文档感觉很痛苦。
就算是我们 java 开发者，也很讨厌看 jdk 的文档。看着不美观，也很累。
swagger-ui 是基于 java 注解的文档生成工具。相对而言比较优雅，也非常强大。
但是缺点也是有的。开发人员要写 jdk 原来的注释 + 注解。注解太多，导致写起来也很痛苦，大部分开发者后来还是选择了放弃。
那么问题来了？我们怎么办才能尽可能的让开发人员，和文档阅读人员都乐于接受呢？
jdk 自带的 doc 就是基于 maven 插件的，本项目也是。
区别如下：
尽可能的保证和 Java 原生注释一致，让开发者很容易就可以使用。
尽可能的信息全面，但是文档简洁。让文档的阅读者享受到等同于手写文档的体验。
将信息的获取和生成区分开。方便用户自己定义自己的输出方式。
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
