快速上手

# 快速上手

该插件主要用于 IDEA 项目快速生成 API 文档,并同步到 Apifox,代码零入侵。

  • 基于 javadoc(Java)、KDoc(Kotlin)、ScalaDoc(Scala) 解析API文档。
  • 支持 Swagger 注解
  • 注意:可以在保持代码零侵入的情况下得到相当完整的 API 文档,但是特殊的需求还是需要部分特殊的注释/注解配合,注释规范说明
  • 该插件基于 easy-api 定制开发,感谢 easy-api 作者

# 功能特性

  • 导出 API 文档到 Apifox
  • 导出 Markdown 格式 API 文档
  • 在 IDEA 中直接发起API请求

# 支持项列表

默认支持 额外(配置)支持
语言 java, kotlin scala
web spring, feign, jaxrs (quarkus / jersey) dubbo
常用框架 javax.validation, Jackson, Gson swagger

# 安装

支持以下IDE

  • IntelliJ IDEA 173+(2017.3+)
  • IntelliJ IDEA Community Edition 173+(2017.3+)

从IDEA仓库中安装

暂不支持,后续会支持

手动下载安装:

  • 下载插件:下载地址
    IDE插件正在内测中,请加下方微信(备注:IDEA),进内测群沟通交流 Apifox 微信群
  • Preferences(Settings) > Plugins > Install plugin from disk...

重启 IDE.

# 配置

  • 打开 Preferences(Settings) > Other Settings > Apifox Uploader image.png

  • Apifox Server: Apifox 开放 API 服务地址,公网SaaS 版为: https://api.apifox.cn

  • Personal Access Token: 个人访问令牌,参考获取访问令牌

  • Module, Project ID and Base Folder Configs: 模块名与项目 ID 的映射,参考获取项目 ID

模块 (Module)

  • 模块名默认为 Controller 上注释第一行,也可通过在 controller 上添加 @module 注释指定
  • 如 Controller 上无注释,则使用 Controller 的类名作为模块名 image.png
  • 一个模块对应 Apifox 中一个项目

Module, Project ID and Base Folder Configs 说明:

  • 每个 Module 都需指定一个 Project ID,同时可以指定 Base Folder。

  • 如果 IDEA 里的项目里的不同模块的接口要同步到多个 Apifox 项目时,则需如下填写模块名:项目 ID,如下表示mall模块的接口同步到项目 530231 根目录,user 模块的接口同步到项目 530232 根目录

    mall:530231
    user:530232
    
  • 也可以如下填写,表示 mall 和 user 模块均导入到项目 530231 的 demo 目录下

    mall:530231,demo
    user:530231,demo
    

Common :

  • log: 一般来说使用一段时间后,log 可以设置为HIGH,减少不必要的输出
    当出现异常情况时,可以设置为LOW,获得更多信息

Support :

  • methodDoc: 勾选后, 允许导出方法文档, 亦可用于导出 rpc 相关文档
    支持导出到markdown

# 内置可选推荐配置

avatar

  • 可以通过勾选来选择需要的配置
  • 内置推荐配置源代码: portal

# 实战

  1. 参考上述文档,下载安装 Apifox Uploader 插件,重启 IDEA。
  2. 打开设置页面,选择 ApifoxUploader,填入 Apifox Server, Personal Access Token,并根据需要,选择相同接口覆盖模式。
  • Apifox Server 默认为 https://api.apifox.cn,非私有化部署用户无需修改。 image.png
  1. 打开需要上传的 Controller 文件,右键选择 Upload to Apifox。 image.png
  2. 填写每个 Module 对应的 Project ID。
  • 仅第一次上传模块时需要,填写后会自动保存至设置中,下次自动读取。 image.png
  1. 上传部分接口,可以点击 Export API,再选择所需上传的接口。 image.pngimage.png
  2. 上传整个项目时,可以在项目根目录点击 Upload to Apifox,插件会自动搜索所有可用的 Controller 文件。
  • 同理,在项目根目录点击 Export API 可以筛选整个项目的接口进行部分上传。 image.png