Intellij IDE 插件--DocumentAssistant 自动RESTful API 文档生成
DocumentAssistant
如今Document Assistant插件已成功发布至IntelliJ IDEA官方插件仓库中。人们都可以在IntelliJ IDEA的插件市场里获取该插件。
今天先向大家介绍一款我自己开发的新插件，在此前研究了很多自动生成文档的方法后发现完全实现零侵入式生成RESTful API文档是完全不可能的。然而今天我想借助IntelliJ IDEA插件的力量实现了真正零侵入式生成RESTful API文档的能力。对编写文档的决心越来越坚定促使我不得不开始开发一个专门解决这一问题的工具。经过三日的努力终于完成了第一个版本DocumentAssistant。
今天想通过这篇博客提出一些想法。目前该插件已实现基础的Markdown文档生成功能，并计划在未来增加自定义模块功能以提升生成能力。我们邀请大家共同维护该插件，并期待其功能能够更加完善以便实现对PDF文件以及Word文档格式的支持。这项非常重要的计划需要更多开发者积极参与进来共同推动项目的进展。近期我将着手进行系统性的工作整理与优化工作
来先看看 我写的小东西。
这是一个非常普通的Spring RestController代码
@RestController
@RequestMapping("/depositOrder")
public class DepositOrderController extends BaseController {
@Autowired
private DepositOrderService depositOrderService;
/** * 充值订单记录搜索
* @param req
* @return
*/
@PostMapping("/searchDepositOrder")
public ResponseBasic<AppPage<DepositOrderSimpleVo>> searchDepositOrder(@RequestBody ReqSearchDepositOrder req){
AppPage<DepositOrderSimpleVo> appPage = this.depositOrderService.searchDepositOrder(req);
return ResponseBasic.ok(appPage);
}
}
代码解释下面就是一个GIF图片显示如何生成
使用方法：1、选中需要生成的方法名称 2、调用生成菜单 3、copy 文档内容
其生成方式是根据如下几点：
接口名称生成：通过接口方法的JAVADOC注释 进行生成。
URI生成：基于application.yml配置中的contextPath和容器中的@RestController类的请求路径；支持使用@PostMapping注解或在Method注解下配置HTTP POST的方式。
基于对象或方法提供的参数动态创建请求参数列表，并结合字段的数据类型及JAVADOC注释实现自动解析功能；支持无限层级嵌套结构的同时处理父类字段的相关信息，并支持泛型数据类型的处理；通过@NotNull注解判断被注入字段是否为空以决定是否注入默认值
通过返回的对象自动完成对字段类型的动态分析。系统会根据输入数据自动生成相应的注释信息，并实现无线级别的嵌套结构。同时能够自主处理父类字段参数的生成过程，并支持泛型数据模型的应用。
获取HTTP 请求方法：使用@Post和@When等关键字进行配置属于POST或GET等多种请求类型
请求方式：通过是否为@RequestBody annotation获得相应信息进行生成。
其中生成的文档如下：
# 搜索充值方案
**请求URL：**
- `/takeatorder/depositScheme/searchDepositScheme `
**请求方式：**
- POST
- RequestBody
###请求参数<业务参数>
|参数名|必选|类型|说明|
|:----|:---|:-----|-----|
|clientId|否|Long|渠道号|
|status|否|Integer|状态 0-待使用 1-使用中 2-已过期|
|denomination|否|Long|面额|
|pageSize|否|Integer|分页大小|
|pageNo|否|Integer|页码|
###返回参数
|参数名|必选|类型|说明|
|:----|:---|:-----|-----|
|code|否|Integer|返回的code码 1是正确|
|message|否|String|服务端返回响应提示信息|
|data|否|Object|服务端响应的实体|
|--content|否|List|content|
|----depositSchemeId|否|Long|方案ID|
|----denomination|否|Long|充值面额|
|----gift|否|Long|赠送金额(元)|
|----clientName|否|String|终端名称|
|----clientId|否|Long|终端ID|
|----status|否|Integer|状态 0-待使用 1-使用中 2-已过期 3-已禁用|
|----statusName|否|String|状态名称|
|----adminUserName|否|String|操作人名字|
|----adminUserId|否|Long|操作人ID|
|----startTime|否|DateTime|开始时间|
|----endTime|否|DateTime|结束时间|
|----createTime|否|DateTime|创建时间|
|----remark|否|String|备注|
|--totalCount|否|Long|总条目数|
|--currentPageNo|否|Long|当前页码|
代码解释已经提交并通过了 intellij ide plugin repository的审核，已经可以提供下载
已经提交并通过了 intellij ide plugin repository的审核
已经提交并通过了 intellij ide plugin repository的审核
Document Assistant 1.1 已经上线并集成最新版本的IDEA功能包。待未来1至2天审核通过后，在官方IDE插件存储库中直接提供本次版本升级包
该版本（Document Assistant 1.2）已进行了更新。目前支持基于IDEA平台的版本为2020.1。待通过官方审核后将在官方IDE插件仓库中直接提供该版本的更新。