最近在写接口的时候一直在想这个接口文档应该怎么搞好一些，要知道一个项目接口数量那么多，我要是一个个写，就算是整个模板在此基础上修改也不是很简单，这个时候我就想了，能不能有一个可以快速便捷的生成接口文档的东西呢？
在此之前我也使用过Swagger这类接口文档工具，但是尽管它的功能十分强大，但是在我仅仅只想快速得到一份完善的接口文档的场景下，还要为其做许多配置我认为是有些繁琐了，然后我就发现了EasyYapi非常符合我需求的插件。
什么是EasyYapi
这是一个IDEA中的插件，简单来说，它可以基于JavaDoc来解析API文档，我们在接口中定义的诸多信息，譬如：请求路径，请求方法，请求头/请求体，包括请求参数与响应示例都可以一键生成，在其官网中有如下介绍：
- 你可以在保持代码零侵入的情况下得到相当完整的API文档，但是特殊的需求还是需要部分特殊的注释/注解配合
- 与之相对的是，你可以灵活的运用配置规则来适应你的项目特性以减少代码侵入
它对于常用的框架与工具都有支持，亦支持多种语言
从官网扒下来的支持项列表如下：
| 默认支持 | 额外(配置)支持 | |
|---|---|---|
| 语言 | Java，Kotlin | scala |
| web | spring，feign，jaxrs (quarkus / jersey) | dubbo |
| 导出到 | Postman，Yapi，Markdown | - |
| 常用框架 | javax.validation，Jackson，Gson | swagger |
安装与配置
该插件目前支持
- IntelliJ IDEA 173+(2017.3+)
- IntelliJ IDEA Community Edition 173+(2017.3+)
你可以直接在IDEA插件仓库中从Marketplace获取，只需搜索EasyYapi并安装即可
或者你也可以从Github Releases下载到最新的插件包后手动安装
截至目前的最新版本是v2.6.0
一般而言，可以不做任何配置直接开始使用，在IDEA->设置->其他设置->EasyAPI中已经提供了许多设置，但在这里我们不能对生成文档的具体结构进行设置，在完全不做配置的情况下生成的Markdown格式文档你会发现除了我们自定义的JavaDoc注释以外全都是英文，虽然看得懂但也多少有点影响可读性。
其实在官方文档中有介绍如何配置，需要在项目的根目录创建一个配置文件来进行设置，如果你想对当前项目下不同的Module生成不同格式的文档，那就需要在对应Module根目录下创建一个同样的配置文件来覆盖项目全局配置。
配置文件支持如下：
| 文件 | 类型 | 适用的操作 |
|---|---|---|
| .easy.api.config | properties | markdown/postman/yapi/call |
| .easy.api.yml/.easy.api.yaml | yml | markdown/postman/yapi/call |
| .postman.config | properties | postman |
| .postman.yml/.postman.yaml | yml | postman |
| .yapi.config | properties | yapi |
| .yapi.yml/.yapi.yaml | yml | yapi |
我们要管理Markdown格式的模板那么直接在根目录下创建一个.easy.api.config文件即可
值得注意的是，由于我的项目中引入了Lombok，所以这个文件会被识别为*.config类型的Lombok配置文件，这样由于类型没有匹配正确会导致很奇怪，所以我们可以在设置->编辑器->文件类型中找到*.properties类型对应的属性这一栏，把我们的配置文件文件名添加进去就可以正确识别了。
要快速配置输出为中文Markdown文档，只需要在配置文件中加上一行载入快速配置即可：
properties.additional=https://raw.githubusercontent.com/tangcent/easy-yapi/master/third/markdown.cn.config或者
properties.additional=https://gitee.com/tangcent/easy-yapi/raw/master/third/markdown.cn.config注意是这一项是Properties类型，如果你是用的是YAML格式要改一下
现在我们就可以开始生成自己项目的接口文档啦，如果还有更多自定义的需求可以查阅Markdown自定义规则来进行更多配置
导出接口文档为Markdown文件
我们在项目结构中单击选择一个类，一个包，或者是一个项目
然后找到右键菜单栏底部的EasyApi，选择Export Markdown
之后选择导出文件的路径即可
然后我们就可以看到一份完善的接口文档了
导出接口文档至Postman
我们在IDEA中可以为EasyApi设置从Postman Integrations Dashboard获得的Token，之后设置一下workspace就可以一键导出到Postman
当然了，我用的是Apifox，但是我也想这么玩咋办？可惜目前这个插件不能直接导入到Apifox里面，不过都这样了为啥不用Swagger数据源URL导入？
不过也可以不配置Postman的Token，这个时候插件就会导出一个Postman格式的Json文件，把这个文件导入Apifox就可以使用了
