本文主要旨在分享个人关注，提高工作效率。 开发基于文档的注释、接口文档生成工具，欢迎各位的指正。
使用源代码和demo地址：传送门
1 .介绍前世
目前大部分项目都是面向前后端分离、前后端并行开发，后端同学在开发前需要写好界面文档。 在许多情况下，开发人员会选择自己手写文档，或者选择使用当前开源的API工具。 包括现在着火的swagger，但也有不少坏处
Swagger分析：
1 )需要添加各种注释以生成规格的接口文档。代码侵入性太强
2 )增加劳动力成本，多管闲事
3 )增加复杂度，代码越多复杂性越差
4 )需要遵守其特殊规范
图标示例：
1.23358www.Sina.com/
那么，我们现在的需求是什么呢？
1 )代码入侵性小，配置简单，层次结构清晰，可输出参数示例demo；
2 )不需要复杂的功能，只要能生成文档就可以了
3 )最好支持成语雀的转换，便于归档
带着好奇心和兴趣开始思考吗？ 如何获取文档注释？
的最大难点是问题：能不能根据参数类中的文档注释生成接口文档呢 ？作为程序员，代码不应该即是文档吗？
不能从编译的代码中获取。 如果思维变了，编译也拿不到，就从没有编译过的文件中获取。
1.3今生
通过文档注释生成界面文档工具，在空闲时间研究开发，基本完成了共享使用。
主要使用的技术要点
IO、反射、Freemarker模板引擎和Markdown语法
2 .功能介绍2.1主要功能代码编译后会自动去除注释；
读取参数类中属性文档的注释； 读取controller方法文档的注释读取接口类的文档注释；(1).读取文档注释
参数级嵌套，父类继承； 支持返回值、通用格式输出(根据几个关键字t、Object、等判断)；(2).支持复杂参数
创建支持集成网关接口的文档，并自定义@OpenApi注释的读取；(3).统一网关类接口文档生成
支持基于接口注释获取请求类型。 示例： @PostMapping；(4).根据注解获取请求类型
根据支持注释**[@NotBlank，@NotNull，@NotEmpty]**确定是否需要参与。(5).根据注解判断参数是否非空；返回参数默认非空
基于注释* * [ http://www.Sina.com/@ decimal min ] * *的输入和输出参数长度支持；(6).根据注解判断参数长度
输出json格式参数Demo示例； 支持基于类型和名称的值模拟；@Max,@Min,@Size,@Length,@DecimalMax,@Range,
生成MD接口文档； 支持复制到语言雀平台，文档格式依然存在；(7).生成JSON示例
支持参数驼峰变换；(8).生成统一结构MD接口文档
参数属性的排序是从类中的属性开始按顺序排序。 接口方法的排序是按照类中的方法从上到下的顺序排序的。 2.2 .优缺点
(9).文档参数类型转换
(1)代码是无创的，不需要添加多馀的注释；
)2)不需要导入依存生成，减少与业务项目的结合度
(3) .可以定制一些功能；
)4)尽快实现对代码文档的期望，减少人工编写接口文档的时间
(10).排序规则
(1) .返回参数多阶段需要使用泛型类型
)2)复制到孔雀石后样式兼容性差
2.3 .示例图3 .特殊规则**注：如果不遵守以下规则，可能无法生成完整的文档或失败。 **
优点：
)1)内部类支持不充分
缺点：
(1) .返回值支持自定义类，需要统一返回Response，增加通用性。 否则将无法获取嵌套返回值。 例如：响应；
)2) .同一controller类的方法名称的提案不同，重复名称时，可能会引起方法注释匹配错误的问题
(3)尚未支持. java .包的返回值。
(4).private方法会自动过滤。
)5) .使用相同方法名称重载的方法可能会发生注释匹配错误。
4 .使用方法文档生成md
文件支持Markdown语法目前支持两种使用方式，方式一：外置工具方式
方式二：依赖jar包+启动类方式
两种方式功能一致，可选择性使用。推荐使用侵入性较小的外置工具方式。 4.1外置工具生成
注：外置工具生成，指的是无需引入工具jar包方式生成
4.1.1精简版使用示例
1).下载工具包
源码地址
注意：下载后解压路径，最好不要有中文路径
可执行jar解压后文件示例
文件介绍
ApiGeneratorConfig.xml > 当前配置文件ApiGeneratorConfig_orgin.xml > 全配置文件api-document-generate.jar > 生成工具Jarstart.bat > Win 系统下启动start.command > ios 系统下启动下载完工具后，可打开源码可执行jar目录下ApiGeneratorConfig.xml配置成相应的自己电脑的示例工程目录即可开始生成
启动注意事项
启动前需要配置好XML文件中的内容；配置文件获取路径默认是当前运行路径下名称为 ApiGeneratorConfig.xml；生成文件默认地址 ：当前运行路径下 generate 文件夹下；Win 系统下启动 双击 start.bat
ios 系统下启动 双击 start.command
4.1.2全功能配置指南
1).根据包地址生成 <?xml version="1.0" encoding="UTF-8" ?><config> <!-- 生成类型 1-根据包地址生成，包下所有类的接口 2-自定义类生成 --> <generateType value="1"/> <!-- 项目下类扫描路径（绝对路径）, 支持多个 --> <projectScanPaths> <path value="/Users/xx/project/api-generate-demo"/> </projectScanPaths> <!-- 包文件夹地址（绝对路径,生成类型为1时必填） --> <apiPackagePath value="/Users/xx/project/api-generate-demo/api-generate-web02/src/main/java/com/example/controller"/></config>
2).根据类地址生成 <?xml version="1.0" encoding="UTF-8" ?><config> <!-- 生成类型 1-根据包地址生成，包下所有类的接口 2-自定义类生成 --> <generateType value="2"/> <!-- 项目下类扫描路径（绝对路径）, 支持多个 --> <projectScanPaths> <path value="/Users/xx/project/workproject/fshows-finance"/> </projectScanPaths> <!-- 类文件地址（绝对路径,生成类型为2时必填）--> <apiClassPaths> <path value="/Users/xx/project/workproject/fshows-finance/fshows-finance-openapi/src/main/java/com/fshows/finance/service/FeeCodeApiService.java"/> <path value="/Users/xx/project/workproject/fshows-finance/fshows-finance-openapi/src/main/java/com/fshows/finance/service/PayableApiService.java"/> </apiClassPaths></config>
3).统一网关类型接口配置 <!-- 开放接口注解类配置, annotationFieldName 默认 "method" --><gateWayField annotationName="com.fshows.finance.common.annotation.OpenApi" annotationFieldName="method"/>
4).根据参数名排除 <!-- 排除参数名配置（支持多个） --><apiExcludeParamNames> <paramName value="nonce"/> <paramName value="sourceType"/></apiExcludeParamNames>
5).根据参数全路径排除 <!-- 排除参数全类名配置（支持多个） --> <apiExcludeParamClassNames> <paramClassName value="com.demo.param.UserLoginResult"/> </apiExcludeParamClassNames>
6).Json示例生成开关 <!-- 是否生成 1-是,2-否 默认1 --><generateJsonFlag value="2"/>
7).参数类型转换 <!-- 参数类型 1-默认,2-驼峰转下划线 --><apiParamType value="2"/>
8).生成文件路径配置
注：生成文件默认名称，Api-generate-MMddHHmmss.md
默认路径是当前项目路径,路径可自定义
9).项目请求地址根路径 <!-- 项目接口访问根路径 默认无 --><projectRootUrl value=""/>
10).自定义统一返回对象
注：一些接口中未包含统一返回对象，但是希望生成的文档包含此结构
参数含义依次为： 参数名, 参数类型, 参数描述, 是否作为父级
是否作为父级标识为是情况下将会，把原先的返回参数添加到该父级下
11).接口头信息输出
针对接口文档存在统一头信息情况下使用，可以在每一个接口中添加头信息参数
<!-- 请求 contentType --><contentType value="application/x-www-form-urlencoded"/><!-- 头信息 --><apiHeaderField> <field name="token" type="String" desc="当前登录用户token" isRequired="1"/></apiHeaderField>5.文件查看
5.1.[推荐]打开工具 系统工具名称官网地址WindowsTyporahttps://www.typora.io/IOSMacDownhttps://macdown.uranusjr.com/
Demo示例图：
4.2.2.文本形式查看
支持以文本形式打开文件，直接拷贝内容粘贴到语雀文档中
注：输出使用的是Markdown 语法，若拷贝到语雀粘贴时请点击进行转换，
建议采用工具打开后，再拷贝到羽雀，
使用文本格式拷贝到语雀后会被重新编译，内容会存在多余的空行。**
转换后示例：
6.附言
万物有痕，可能会有一些未考虑到场景或问题，欢迎大佬指点。
公众号
更多精彩内容、编程故事、心得分享，欢迎关注公众号