写点什么

写文档太麻烦,试试这款 IDEA 插件吧!

发布于: 2020 年 11 月 02 日
写文档太麻烦,试试这款 IDEA 插件吧!

前言


每次开发完新项目或者新接口功能等,第一件事就是提供接口文档。说到接口文档,当然是用 Markdown 了。各种复制粘贴字段,必填非必填,字段备注,请求返回示例等等。简直是浪费时间哇。所以想到了开发一款插件来解决重复复制文档的问题。下面来看我介绍介绍这款插件。


PS:插件比较简陋,还需要不断迭代。


公众号:liuzhihangs,记录工作学习中的技术、开发及源码笔记;时不时分享一些生活中的见闻感悟。欢迎大佬来指导!


为什么开发插件


每次在对外提供接口时都要写文档,各种麻烦,并且文档耗费了很大一部分时间。也使用了一些文档工具,在线写作工具,最终还是比较喜欢自己手写文档。


使用过的生成工具


  1. Swagger : 添加依赖,配置类及描述信息,然后在方法及实体上添加注解,启动项目便可以通过访问 xxxx/swagger-ui.html 查看接口文档;

  2. API Doc :添加配置文件及注释,安装 npm 并通过执行命令生成文档;

  3. SmartDoc :添加依赖及注释后执行测试类生成文档;

  4. API2DOC :添加依赖,开启注解,通过注解配置生成文档。


上面四种方法,无疑都需要添加依赖,使用注解等方式,可以说有一定的代码侵入性。


使用过的接口文档工具


  1. ShowDoc :曾经一段时间很喜欢用这个, Markdown 语法,方便直观。不过就是要自己手写;

  2. YApi :现在在使用 YApi,可以通过 Swagger 导入;

  3. VS Code 写 Markdown :直接离线写 Markdown ,可以导出 PDF、Word、Html。


自己写文档比较重复,繁琐,不过个人比较喜欢 Markdown 格式。简洁直观。并且配合着我之前写的 IDEA 插件 copy-as-jsonTookit 将实体复制为 json 字符串,用来快速生成请求样例和返回样例,还是可以减少一定的工作量的。


其他使用方式


使用各种在线协作工具,腾讯文档、语雀、石墨文档。使用离线版本 PDF、Word、Excel 等等。也有一些其他的文档工具,不过自己都没有使用过或者调研过了。


基本上这些文档工具要么通过代码侵入的方式生成文档,要么自己手撸文档。总体来说各有千秋。


个人手写更方便


个人比较喜欢的就是手写 Markdown 。


下面是两幅图:




有时候文档比较多的时候,就写的累了。尤其是最近使用了 YApi , 个人感觉使用 Swagger 然后导入到 YApi 里面还是挺方便的,省时省力。


后来就想,既然 YApi 提供接口,那我是不是可以自己生成,然后传到 YApi 中呢?


所以就开始着手这个插件的开发。


使用及功能


既然已经开发好最基础版本了,当然也得介绍下,首先看图:



通过图简单介绍下使用以及功能:


使用


使用方式很简单,直接在 Controller 类或者 Controller 类的公共非静态方法内右键唤出菜单,单机 Doc View 即可。



只能在 Controller 类或者 Controller 类的公共非静态方法内使用。至于两者的区别,后续会介绍。


这里可能会有小伙伴们发出疑问:Dubbo 接口也要写文档,难道不可以么?


嗯~ 可以!但是现在不支持~


功能


基本功能就是截图展示的那样。


  1. 左侧显示接口名及列表,右侧展示接口信息;

  2. 点击 Copy 按钮 就会将展示的信息原本对应的 Markdown 文本复制到剪贴板;

  3. 在 Class 内部点击,生成的如图所示的列表,而在方法内右键生成的是只有本方法的。


使用说明


Dubbo 接口,当前版本不支持,所以下面介绍的全都是在 Class 上的使用:


要生成文档,需要满足什么条件?


  1. 目标类内部有方法;

  2. 类必须有相关 Spring 注解。

1. org.springframework.stereotype.Controller

2. org.springframework.web.bind.annotation.RestController


生成文档,接口方法需要满足什么条件?


文档的方法:Public 修饰且非静态方法(static 修饰),方法上包含以下注解:


  1. org.springframework.web.bind.annotation.GetMapping

  2. org.springframework.web.bind.annotation.PostMapping

  3. org.springframework.web.bind.annotation.GetMapping

  4. org.springframework.web.bind.annotation.DeleteMapping

  5. org.springframework.web.bind.annotation.PatchMapping

  6. org.springframework.web.bind.annotation.RequestMapping


文档模版是否可以设置?


当前版本文档模版只有展示的这个,不支持自定义模版。


接口名称是如何设置的?


  1. 接口名称默认取值如图截图所示 类名#方法名


  1. 支持在注释上使用 @name 设置接口名。



接口描述是从哪里获取的?


  1. 接口描述直接取的方法注释;

  2. 如果有 @description 标签,则会优先使用标签对应的描述。



请求路径是如何生成的?


ClassMethod 上的 path 进行拼装组成。


请求方式如何设置?


根据 Method 上的注解生成。


请求参数及请求示例的需要设置什么?


  1. 根据是否有 @RequestBody 注解,生成请求 Header 是否为 json 还是 form。同时会检测请求参数中是否有 @RequestHeader 注解;



  1. 对象生成列表;

  2. 根据请求是 json 还是 form 生成对应的请求示例。


返回参数及返回示例怎么生成?


支持对象,返回空,返回带泛型方式。这里的泛型仅支持单个泛型且名称为 T



总结


Q&A


**Q: Doc View 插件去哪里下载?**


A:


  1. 可以直接通过 IDEA 插件仓库,直接搜索名称即可;

  2. 在 GitHub 通过 Releases 下载;

  3. 关注公众号并发送 Doc View 相关关键字(doc/doc view)获取。


**Q: Doc View 是否开源?**


A: 是的。开源地址为:https://github.com/liuzhihang/doc-view,有兴趣的小伙伴,可以给个 Star ,如果想增加一些功能,也可以提 PR。


结束语


插件开发从最开始开发到今天发布第一版,中间经历了很长一段时间,毕竟只是业余时间开发,就断断续续的写,不过现在最简单版本已经可以使用了。


目前来看,只有一个 Copy 功能,不过基本上可以满足使用。至于其他的需求,比如:自定义模版、支持 Dubbo 接口、预览导出等功能就需要后续不断迭代了。


个人开发精力有限,小伙伴在使用过程中遇到肯定会遇到 bug,或者是有其他的功能及使用建议,都可以通过以下方式反馈:


  1. 关注公众号:『 刘志航 』 通过读者讨论进行留言;

  2. 在 GitHub 上提 Issues;

  3. 在插件帮助页面留言;

  4. 文章结尾留言;


最后,感谢小伙伴们的支持。欢迎下载体验,并提出相关建议及意见。


发布于: 2020 年 11 月 02 日阅读数: 1787
用户头像

个人公众号:『 程序员小航 』 2020.07.30 加入

某不知名互联网公司 Java 程序员一枚。记录工作学习中的技术、开发及源码笔记;分享生活中的见闻感悟。

评论

发布
暂无评论
写文档太麻烦,试试这款 IDEA 插件吧!