前言
每次开发完新项目或者新接口功能等，第一件事就是提供接口文档。说到接口文档，当然是用 Markdown 了。各种复制粘贴字段，必填非必填，字段备注，请求返回示例等等。简直是浪费时间哇。所以想到了开发一款插件来解决重复复制文档的问题。下面来看我介绍介绍这款插件。
PS：插件比较简陋，还需要不断迭代。
为什么开发插件
每次在对外提供接口时都要写文档，各种麻烦，并且文档耗费了很大一部分时间。也使用了一些文档工具，在线写作工具，最终还是比较喜欢自己手写文档。
使用过的生成工具
- Swagger ： 添加依赖，配置类及描述信息，然后在方法及实体上添加注解，启动项目便可以通过访问
xxxx/swagger-ui.html查看接口文档； - API Doc ：添加配置文件及注释，安装
npm并通过执行命令生成文档； - SmartDoc ：添加依赖及注释后执行测试类生成文档；
- API2DOC ：添加依赖，开启注解，通过注解配置生成文档。
上面四种方法，无疑都需要添加依赖，使用注解等方式，可以说有一定的代码侵入性。
使用过的接口文档工具
- ShowDoc ：曾经一段时间很喜欢用这个， Markdown 语法，方便直观。不过就是要自己手写；
- YApi ：现在在使用 YApi，可以通过 Swagger 导入；
- VS Code 写 Markdown ：直接离线写 Markdown ，可以导出 PDF、Word、Html。
自己写文档比较重复，繁琐，不过个人比较喜欢 Markdown 格式。简洁直观。并且配合着我之前写的 IDEA 插件 copy-as-json 和 Tookit 将实体复制为 json 字符串，用来快速生成请求样例和返回样例，还是可以减少一定的工作量的。
其他使用方式
使用各种在线协作工具，腾讯文档、语雀、石墨文档。使用离线版本 PDF、Word、Excel 等等。也有一些其他的文档工具，不过自己都没有使用过或者调研过了。
基本上这些文档工具要么通过代码侵入的方式生成文档，要么自己手撸文档。总体来说各有千秋。
个人手写更方便
个人比较喜欢的就是手写 Markdown 。
下面是两幅图：
有时候文档比较多的时候，就写的累了。尤其是最近使用了 YApi ， 个人感觉使用 Swagger 然后导入到 YApi 里面还是挺方便的，省时省力。
后来就想，既然 YApi 提供接口，那我是不是可以自己生成，然后传到 YApi 中呢？
所以就开始着手这个插件的开发。
使用及功能
既然已经开发好最基础版本了，当然也得介绍下，首先看图：
通过图简单介绍下使用以及功能：
使用
使用方式很简单，直接在 Controller 类或者 Controller 类的公共非静态方法内右键唤出菜单，单机 Doc View 即可。
只能在 Controller 类或者 Controller 类的公共非静态方法内使用。至于两者的区别，后续会介绍。
这里可能会有小伙伴们发出疑问：Dubbo 接口也要写文档，难道不可以么？
嗯~ 可以！但是现在不支持~
功能
基本功能就是截图展示的那样。
- 左侧显示接口名及列表，右侧展示接口信息；
- 点击
Copy 按钮就会将展示的信息原本对应的 Markdown 文本复制到剪贴板； - 在 Class 内部点击，生成的如图所示的列表，而在方法内右键生成的是只有本方法的。
使用说明
Dubbo 接口，当前版本不支持，所以下面介绍的全都是在 Class 上的使用：
要生成文档，需要满足什么条件？
- 目标类内部有方法；
- 类必须有相关
Spring注解。
org.springframework.stereotype.Controllerorg.springframework.web.bind.annotation.RestController
生成文档，接口方法需要满足什么条件？
文档的方法：Public 修饰且非静态方法（static 修饰），方法上包含以下注解：
org.springframework.web.bind.annotation.GetMappingorg.springframework.web.bind.annotation.PostMappingorg.springframework.web.bind.annotation.GetMappingorg.springframework.web.bind.annotation.DeleteMappingorg.springframework.web.bind.annotation.PatchMappingorg.springframework.web.bind.annotation.RequestMapping
文档模版是否可以设置？
当前版本文档模版只有展示的这个，不支持自定义模版。
接口名称是如何设置的？
- 接口名称默认取值如图截图所示
类名#方法名；
网络异常，图片无法展示| - 支持在注释上使用
@name设置接口名。
网络异常，图片无法展示|
接口描述是从哪里获取的？
- 接口描述直接取的方法注释；
- 如果有
@description标签，则会优先使用标签对应的描述。
网络异常，图片无法展示|
请求路径是如何生成的？
取 Class 和 Method 上的 path 进行拼装组成。
请求方式如何设置？
根据 Method 上的注解生成。
请求参数及请求示例的需要设置什么？
- 根据是否有
@RequestBody注解，生成请求 Header 是否为 json 还是 form。同时会检测请求参数中是否有@RequestHeader注解；
网络异常，图片无法展示| - 对象生成列表；
- 根据请求是 json 还是 form 生成对应的请求示例。
返回参数及返回示例怎么生成？
支持对象，返回空，返回带泛型方式。这里的泛型仅支持单个泛型且名称为 T。
总结
Q&A
Q: Doc View 插件去哪里下载？
A:
- 可以直接通过 IDEA 插件仓库，直接搜索名称即可；
- 在 GitHub 通过 Releases 下载；
- 关注公众号并发送
Doc View相关关键字（doc/doc view）获取。
Q: Doc View 是否开源？
A: 是的。开源地址为：github.com/liuzhihang/…，有兴趣的小伙伴，可以给个 Star ，如果想增加一些功能，也可以提 PR。
结束语
插件开发从最开始开发到今天发布第一版，中间经历了很长一段时间，毕竟只是业余时间开发，就断断续续的写，不过现在最简单版本已经可以使用了。
目前来看，只有一个 Copy 功能，不过基本上可以满足使用。至于其他的需求，比如：自定义模版、支持 Dubbo 接口、预览导出等功能就需要后续不断迭代了。
个人开发精力有限，小伙伴在使用过程中遇到肯定会遇到 bug，或者是有其他的功能及使用建议，都可以通过以下方式反馈：
- 关注公众号：『 刘志航 』 通过读者讨论进行留言；
- 在 GitHub 上提 Issues；
- 在插件帮助页面留言；
- 文章结尾留言；
最后，感谢小伙伴们的支持。欢迎下载体验，并提出相关建议及意见。
