java 文档自动生成的神器 idoc
写文档作为一名开发者，每个人都要写代码。
工作中，几乎每一位开发者都要写文档。
因为工作是人和人的协作，产品要写需求文档，开发要写详细设计文档，接口文档。
可是，作为一个懒人，平时最讨厌的一件事情就是写文档。
写文档最令我不爽的地方是在于代码备注要改一遍，然后文档再改一遍。
所有重复的劳作，都是对于我们宝贵摸鱼时间的最大浪费。
于是，我就常常想，能不能只写一遍呢？
i-doc项目简介idoc为java项目生成项目文档。
基于原生的java注释，尽可能的生成简介的文档。用户可以自定义自己的模板，生成自己需要的文档。
实现原理：基于maven插件，类似于javadoc。可以更加灵活，允许用户自定义。
特性（1）基于maven项目生成包含大部分信息的元数据
（2）默认支持markdown简化文档的生成，支持自定义模板
（3）支持用户自定义文档生成器
（4）支持用户自定生成文档的类过滤器
（5）添加字段类型别名，支持用户自定义
快速入门需要jdk1.8+
maven3.x+
maven引入使用maven引入当前idoc插件。
com.github.houbbidoc-core0.3.0测试对象的创建为了演示文档，我们创建了一个Address对象。
packagecom.github.houbb.idoc.test.model;/***地址*@authorbinbin.hou*@since0.0.1*/publicclassAddress{/***城市*/privateStringcountry;/***街道*/privateStringstreet;publicStringgetCountry(){returncountry;}publicvoidsetCountry(Stringcountry){this.country=country;}publicStringgetStreet(){returnstreet;}publicvoidsetStreet(Stringstreet){this.street=street;}}执行插件mvncom.github.houbb:idoc-core:0.3.0:idoc命令行日志信息[INFO]------------------------------------Startgeneratedoc[INFO]共计【1】个文件待处理，请耐心等待。进度如下：====================================================================================================100%[INFO]GeneratordocwithdocGenerator: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]------------------------------------Finishgeneratedoc更多生成方式当然，你可以发现这里只是把元数据进行输出到控台，意义不大。
我们可以根据需求，自定义实现生成类。
比如下面的方式，可以使用内置的MarkdownDocGenerator输出到markdown文件。
com.github.houbbidoc-core0.3.0com.github.houbb.idoc.ftl.api.generator.MarkdownDocGeneratorcom.github.houbbidoc-ftl0.3.0效果可以参考：
heaven文档目录
ps:heaven项目是个人整理了多年的工具包，几百个类，手写文档估计要很久。
设计初衷节约时间Java文档一直是一个大问题。
很多项目不写文档，即使写文档，对于开发人员来说也是非常痛苦的。
不写文档的缺点自不用多少，手动写文档的缺点也显而易见：
非常浪费时间，而且会出错。
无法保证及时更新。代码已经变了，但是文档还要同步修改。需要强制人来维护这一种一致性。这很难。
为什么不是swagger-uijava的文档有几类：
jdk自带的doc生成。这个以前实践给别人用过，别人用C#，看到java的默认文档感觉很痛苦。就算是我们java开发者，也很讨厌看jdk的文档。看着不美观，也很累。
swagger-ui是基于java注解的文档生成工具。相对而言比较优雅，也非常强大。但是缺点也是有的。开发人员要写jdk原来的注释+注解。注解太多，导致写起来也很痛苦，大部分开发者后来还是选择了放弃。
那么问题来了？我们怎么办才能尽可能的让开发人员，和文档阅读人员都乐于接受呢？
jdk自带的doc就是基于maven插件的，本项目也是。
区别如下：
尽可能的保证和Java原生注释一致，让开发者很容易就可以使用。
尽可能的信息全面，但是文档简洁。让文档的阅读者享受到等同于手写文档的体验。
将信息的获取和生成区分开。方便用户自己定义自己的输出方式。
参数配置说明为了更加灵活的实现文档的生成和文档元数据的生成，提供如下参数
插件配置属性简介属性是否必填说明默认值备注encoding否项目编码UTF-8includes否元数据包含的文件信息**/*.java默认扫描所有java文件excludes否元数据排除的文件信息无默认不排除isOverwriteWhenExists否文档存在时是否覆盖trueisAllInOne否所有类信息是否生成单个文档true命令行文档生成器，此属性无意义。generates否文档生成类命令行文档生成信息可以同时指定多个。类名全称。用户自定义参见com.github.houbb.idoc.api.core.genenrator.IDocGeneratorgenerateFilters否文档生成类过滤器无可以同时指定多个。类名全称。用户自定义参见com.github.houbb.idoc.api.core.filter.IDocGenerateFiltertargetDir否生成目标文件目录无自定义指定文档生成的文件夹isAllInOne简单的文档，建议直接生成在一个文件。
如果较为复杂，则可以设为false，则会按照
generates相关问题默认的命令行文档，主要用于演示和信息查看，不具有实际意义。
建议引入idoc-ftl模块，使用MarkdownDocGenerator生成器。
可以同时指定多个。
可引入idoc-api自行定义。
generateFilters建议实际的文档，主要关心定义的方法。
我们可以针对DocClass的包名，过滤只生成Service方法文档。
如果是在以前的基础上，则可以加上@since@version等信息的过滤。
可以同时指定多个。
可引入idoc-api自行定义。
自定义Filter可以参考当前项目的idoc-test模块。
整体配置如下:
com.github.houbbidoc-core0.3.0truecom.github.houbb.idoc.ftl.api.generator.MarkdownDocGeneratorcom.github.houbb.idoc.test.filter.MyGenerateFiltercom.github.houbbidoc-test${project.version}指定文档生成器指定使用Markdown文档生成器，可以同时指定多个。
com.github.houbb.idoc.ftl.api.generator.MarkdownDocGenerator引入包MarkdownDocGenerator在idoc-ftl模块中，需要引入对应的依赖。
当然idoc-core默认依赖idoc-ftl。
指定文件生成类的过滤器如果不定义自己的类生成过滤器，则会生成所有的类信息。
一般使用中我们只关心service方法，所以添加了类的过滤实现。
实现如下：
引入idoc-api包com.github.houbbidoc-api${project.version}实现IDocGenerateFilterpackagecom.github.houbb.idoc.test.filter;importcom.github.houbb.idoc.api.core.filter.IDocGenerateFilter;importcom.github.houbb.idoc.api.model.metadata.DocClass;/***自定义生成过滤器*@authorbinbin.hou*@since0.0.1*/publicclassMyGenerateFilterimplementsIDocGenerateFilter{@Overridepublicbooleaninclude(DocClassdocClass){if("QueryUserService".equalsIgnoreCase(docClass.getName())){returntrue;}returnfalse;}}插件中配置使用com.github.houbb.idoc.test.filter.MyGenerateFilter注意，也需要将你定义这个过滤器的jar添加依赖，否则无法找到对应的类信息。
com.github.houbbidoc-test${project.version}类代码信息User信息/***用户信息*@authorbinbin.hou*@since0.0.1*/publicclassUser{/***名称*@require是*@remark中文名称，请认真填写*/privateStringname;/***年龄*/privateintage;/***生日*/privateDatebirthday;/***地址*/privateListaddressList;/***伴侣*/privateUsermate;//...}i-doc定义的标签@require表示当前字段是否必填，作为方法入参时。
@remark表示当前字段的备注信息。
方法类信息QueryUserService.java/***查询用户服务类*@authorbinbin.hou*@since0.0.1*/publicinterfaceQueryUserService{/***根据用户信息查询用户*@paramuser用户信息*@return结果*@since0.0.2,2019/02/12*/publicUserqueryUser(finalUseruser);}执行插件mvncom.github.houbb:idoc-core:0.3.0:idoc日志信息[INFO]------------------------------------Startgeneratedoc[INFO]共计【4】个文件待处理，请耐心等待。进度如下：====================================================================================================100%[INFO]GeneratordocwithdocGenerator:com.github.houbb.idoc.ftl.api.generator.MarkdownDocGenerator[INFO]Markdown生成文档文件allinone路径:/Users/houbinbin/code/_github/idoc/idoc-test/src/main/resources/idoc-gen/idoc-test-全部文档.md[INFO]------------------------------------Finishgeneratedoc文档信息当前文件路径日志会打印，比如我自己测试的为：
/Users/houbinbin/code/_github/idoc/idoc-test/src/main/resources/idoc-gen/idoc-test-全部文档.md
文档生成效果参见文档:
idoc-test-全部文档.md
字段类型别名支持可以参考当前项目的idoc-test模块。
为什么需要有时候页面显示类型，希望更加友好。
所以系统内置了一些别名显示，也同时支持自定义别名。
类型字段的别名系统内置系统当前版本提供了常见的别名。
详情见com.github.houbb.idoc.core.util.JavaTypeAliasUtil
类型别称java.lang.Float浮点型java.lang.Double浮点型java.util.Date日期java.time.LocalDateTime日期时间java.util.Currency货币float浮点型java.lang.Integer整型long长整型java.math.BigDecimal数字java.lang.Character字符java.lang.Long长整型java.lang.Short短整型java.util.Map映射java.time.LocalTime时间java.lang.Boolean布尔值java.math.BigInteger数字java.lang.String字符串java.lang.Byte字节double浮点型byte字节java.util.Collection集合int整型java.util.List列表boolean布尔值java.time.LocalDate日期char字符short短整型void空array数组自定义的方式可以通过typeAlias指定自定义的字段别称。
com.github.houbb.idoc.test.filter.MyGenerateFiltertruejava.lang.StringString自定义说明优先级用户自定义的字段别名优先级高于系统默认。
后面定义的别名会直接覆盖前面的别名。
测试代码演示对象定义/***别名测试*@authorbinbin.hou*@since0.0.1*/publicclassTypeAliasSimpleBean{/***名称*/privateStringname;publicStringgetName(){returnname;}publicvoidsetName(Stringname){this.name=name;}}测试日志运行测试日志如下：
{"comment":"别名测试","docAnnotationList":[],"docFieldList":[{"comment":"名称","name":"name","type":"java.lang.String","typeAlias":"String自定义说明"}],"docMethodList":[{"docMethodParameterList":[],"docMethodReturn":{"fullName":"java.lang.String","name":"String","packageName":"java.lang"},"docTagList":[],"exceptionList":[],"modifiers":["public"],"name":"getName","seeList":[],"signature":"getName()"},{"docMethodParameterList":[{"docAnnotationList":[],"name":"name","type":"java.lang.String","typeAlias":"String自定义说明"}],"docMethodReturn":{},"docTagList":[],"exceptionList":[],"modifiers":["public"],"name":"setName","seeList":[],"signature":"setName(name)"}],"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.TypeAliasSimpleBean","modifiers":["public"],"name":"TypeAliasSimpleBean","packageName":"com.github.houbb.idoc.test.model"}其中typeAlias就是字段类型的别名，我们可以用来更加友好的显示字段信息。
其他的思考自定义方式的便利性自定义的方式采用基于xml的方式是比较方便。
但是数量比较多的时候就没有那么方便，本来考虑添加对应的配置属性接口，权衡下还是使用了xml配置的方式。
是否使用comment信息？如果一个字段，没有指定别名，是否使用comment信息做替代？
建议使用，当前版本不做处理。
为什么使用比起冗长的类信息，大部分人更乐于看到解释。
如果是针对同构的系统(都是java语言)，则可以理解。
如果是针对异构的系统(比如前台是php)，则不易于理解。
为什么不处理大部分的接口都是常见字段,性价比不高。
可能存在字段没有些comment的情况，会导致判断的复杂性。
如果用户不想使用别名直接修改模板即可，使用原来的字段type属性即可。
开源地址https://github.com/houbb/idoc
当然，这个项目还有很长的路要走。
如果喜欢，欢迎forkstar~
Java通过docx模板生成docx
需要通过，某模板生成固定格式的docx文档时，可采用该方法。步骤主要有以下几步：1.准备好模板docx,把你需要的替换成指定的格式名称如：${待替换的key},具体文本如下我们把需要填充的内容都替换成了指定的key，这样后续方便替换。2.下面上代码：
//若前端调用后有其余操作推荐使用返回值，单纯的下载的话void即可publicClientRespexport(ConflictResolutionEntityentity,HttpServletResponseresponse)throwsIOException{//将实体类转为mapMapresult=TransferUtil.convertBeanToMap(entity);/**获取模板文件的路径，并将模板文件拷贝到指定路径下，如果只需要在jar包中启动的话直接获取jar的相对资源路径获取即可（放在src/main/resources/你的自定义文件的下面，注意不要加斜杠，否则会导致获取不到路径报错）**/StringdocPath=this.getResourceFilePath("contradiction.docx");//设置响应体的请求头，Cont