本文主要分享一个基于个人兴趣，旨在提高工作效率，开发了一个基于文档注释，接口文档生成工具，欢迎大佬指点。

源码以及使用demo地址：传送门

1.前置介绍

1.1前世

现在大多数项目都走向了前后端分离，前后端并行开发，这就需要后端同学在开发前先写好接口文档。很多时候开发人员一般都会选择，自己手写文档，或者使用目前开源的API工具，包括现在比较火的swagger但劣势也不少

Swagger分析：
1).为生成规范的接口文档，需要添加各种各样的注解，代码侵入性太强；
2).增加了人工成本，做了多余的事;
3).增加复杂度，代码越多复杂性越差；
4).需要遵守其特殊的规范；

图示示例：

1.2深思

问题：能不能根据参数类中的文档注释生成接口文档呢？作为程序员，代码不应该即是文档吗？
那我们现在的需求是什么呢？
1).代码侵入性小，配置简单、层级结构清晰、可输出参数示例demo；
2).无需太复杂的功能，只要可以生成文档即可；
3).最好是支持转换成语雀，方便存档；

带着好奇心与兴趣开始考虑？如何获取文档注释？
遇到的最大难点就是：代码编译后会自动去除注释；
从编译后的代码里获取肯定是行不通的。思维转变，编译后取不到，那就从未编译的文件里获取。

1.3今生

根据文档注释生成接口文档工具，在空余时间研究并开发，已经基本完成分享使用。

主要用到的技术点

IO、反射、Freemarker模板引擎、Markdown语法

2.功能介绍

2.1主要功能

(1).读取文档注释

读取参数类中属性文档注释；
读取controller方法文档注释；
读取接口类文档注释；

(2).支持复杂参数

参数层级嵌套，继承父类；
支持返回值，泛型格式输出（根据一些关键词 T、Object、、等判断的）；

(3).统一网关类接口文档生成

支持生成统一网关接口的文档，自定义@OpenApi注解的读取；

(4).根据注解获取请求类型

支持根据接口注解获取请求类型，示例：@PostMapping；

(5).根据注解判断参数是否非空

支持根据注解**[@NotBlank,@NotNull,@NotEmpty]**判断入参是否必填，返回参数默认非空；

(6).根据注解判断参数长度

支持根据注解**[@Max,@Min,@Size,@Length,@DecimalMax,@Range,@DecimalMin] **输出入参长度；

(7).生成JSON示例

支持输出json格式参数Demo示例；
支持根据类型以及名称模拟值；

(8).生成统一结构MD接口文档

生成MD接口文档；
支持拷贝到语雀平台，文档格式依然存在；

(9).文档参数类型转换

支持参数驼峰转下划线转换 ;

(10).排序规则

参数属性排序 > 以类中属性从上往下顺序排序；
接口方法排序 > 以类中方法从上往下顺序排序；

2.2.优缺点

优点:
(1).代码非侵入性，无需添加一些无用的注解；
(2).无需引入依赖生成，减少与业务项目耦合度；
(3).可以自定义一些功能；
(4).早日实现代码即文档的期盼，减少人工编写接口文档的时间；

缺点：
(1).返回参数多级需要使用泛型；
(2).拷贝到语雀后样式兼容差强人意；

2.3.示例图

3.特殊规则

** 注：未按照如下规则，可能会导致无法生成完整文档或失败。**

3.1参数类文档注释匹配-特殊规则
(1).内部类支持不太完善；

3.2Controller接口方法类规则
(1).返回值支持自定义类，统一返回Response,需要加泛型，否则获取不到嵌套的返回值，示例：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 > 生成工具Jar
start.bat > Win 系统下启动
start.command > ios 系统下启动

下载完工具后，可打开源码可执行jar目录下ApiGeneratorConfig.xml配置成相应的自己电脑的示例工程目录即可开始生成

2).配置ApiGeneratorConfig.XML

<?xml version="1.0" encoding="UTF-8" ?>
<config><!-- 生成类型 1-根据包地址生成，包下所有类的接口 2-自定义类生成 --><generateType value="1"/><!-- 项目下类扫描路径（绝对路径）, 支持多个 , 一般是项目根路径 --><projectScanPaths><path value="/Users/xx/project/api-generate-demo"/></projectScanPaths><!-- 包文件夹地址（绝对路径,生成类型为1时必填） --><apiPackagePathvalue="/Users/xx/project/api-generate-demo/api-generate-web02/src/main/java/com/example/controller"/><!-- 类文件地址（绝对路径,生成类型为2时必填）--><apiClassPaths><path value=""/></apiClassPaths></config>

启动注意事项

启动前需要配置好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时必填） --><apiPackagePathvalue="/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
默认路径是当前项目路径,路径可自定义

<!-- 生成文件地址(默认：当前目录) -->
<generateFilePath value="/Users/mengqiang/Desktop/api-generate-tool/finance/openapi"/>

9).项目请求地址根路径

<!-- 项目接口访问根路径 默认无 -->
<projectRootUrl value=""/>

10).自定义统一返回对象

注：一些接口中未包含统一返回对象，但是希望生成的文档包含此结构
参数含义依次为：参数名, 参数类型, 参数描述, 是否作为父级
是否作为父级标识为是情况下将会，把原先的返回参数添加到该父级下

<!-- 自定义顶级返回对象属性 -->
<apiRootResField><field name="success" typeClassName="java.lang.Boolean" desc="请求是否成功" isParent="0"/><field name="data" typeClassName="java.lang.Object" desc="" isParent="1"/><field name="errorCode" typeClassName="java.lang.String" desc="错误码" isParent="0"/><field name="errorMsg" typeClassName="java.lang.String" desc="错误信息" isParent="0"/>
</apiRootResField>

11).接口头信息输出

针对接口文档存在统一头信息情况下使用，可以在每一个接口中添加头信息参数

<!-- 请求 contentType -->
<contentType value="application/x-www-form-urlencoded"/><!-- 头信息 -->
<apiHeaderField><field name="token" type="String" desc="当前登录用户token" isRequired="1"/>
</apiHeaderField>

5.文件查看

5.1.[推荐]打开工具

系统	工具名称	官网地址
Windows	Typora	https://www.typora.io/
IOS	MacDown	https://macdown.uranusjr.com/

Demo示例图：

4.2.2.文本形式查看

支持以文本形式打开文件，直接拷贝内容粘贴到语雀文档中

注：输出使用的是Markdown 语法，若拷贝到语雀粘贴时请点击进行转换，
建议采用工具打开后，再拷贝到羽雀，
使用文本格式拷贝到语雀后会被重新编译，内容会存在多余的空行。**

转换后示例：

6.附言

万物有痕，可能会有一些未考虑到场景或问题，欢迎大佬指点。

公众号
更多精彩内容、编程故事、心得分享，欢迎关注公众号

基于文档注释接口文档生成工具(代码0侵入附源码)相关推荐

【QT/C++】基于QT开发的一款A-SOUL元素的视频播放器（附源码）
[QT/C++]基于QT开发的一款关于A-SOUL的视频播放器(附源码) 前言一.软件使用说明 1.运行软件的界面如下 2.操作软件的步骤二.软件设计说明 1.UI界面的设计 2.主代码中的部分函 ...
一文看尽深度学习中的20种卷积（附源码整理和论文解读）
点击上方"3D视觉工坊",选择"星标" 干货第一时间送达引言卷积,是卷积神经网络中最重要的组件之一.不同的卷积结构有着不一样的功能,但本质上都是用于提取特征 ...
2021-06-26一文看尽深度学习中的20种卷积（附源码整理和论文解读）
卷积,是卷积神经网络中最重要的组件之一.不同的卷积结构有着不一样的功能,但本质上都是用于提取特征.比如,在传统图像处理中,人们通过设定不同的算子来提取诸如边缘.水平.垂直等固定的特征.而在卷积神经网络 ...
手把手！基于领域预训练和对比学习SimCSE的语义检索（附源码）
之前看到有同学问,希望看一些偏实践,特别是带源码的那种,安排!今天就手把手带大家完成一个基于领域预训练和对比学习SimCSE的语义检索小系统. 所谓语义检索(也称基于向量的检索),是指检索系统不再拘泥 ...
基于SSM框架简易项目“书籍管理系统”，超详细讲解，附源码
目录我有话说: 1 项目简介 2 项目展示 2.1 首先创建数据库和表信息 2.2 预先准备操作 2.3 开始配置项目 2.4 开始web层 3 图片展示 4 附上源码文件(百度网盘): 我有话说: ...
基于Vue+Express+Mysql开发的手机端电影购票系统（附源码）
基于Vue+Express+Mysql开发的手机端电影购票系统基于手机的电影购票系统-Vue+Node 一个Vue+Express+Mysql的电影售票项目项目完整源码下载 https://dow ...
非对称加密实战(一)：JDK生成keystore获取公钥私钥及代码验证【附源码】
目录使用说明非对称加密生成keystore文件公钥私钥互相解密获取fd-alias.keystore中的公钥私钥使用生成公钥私钥进行解密源码地址使用说明非对称加密非对称加密算法主要 ...
基于Matlab使用线性FM波形对带状合成孔径雷达系统建模（附源码）
目录一.合成孔径雷达成像二.雷达配置三.场景配置四.SAR 信号模拟五.总结六.程序此示例说明如何使用线性 FM (LFM) 波形对基于带状图的合成孔径雷达 (SAR) 系统进行建模.S ...
【Android +Tensroflow Lite】实现从基于机器学习语音中识别指令讲解及实战（超详细附源码和演示视频）
需要源码和配置文件请点赞关注收藏后评论区留言~~~ 一.基于机器学习的语音推断 Tensorflow基于分层和模块化的设计思想,整个框架以C语言的编程接口为界,分为前端和后端两大部分 Tensorfl ...

基于文档注释接口文档生成工具(代码0侵入附源码)