IDEA 插件上新！ 生成接口文档就是这么快！

当有接口对接需求的时候，开发终于不用再担心 API 文档难写了，也不用再一个个接口文档重新写！安装这个 IDEA 插件，可以一步将文档导入到 Postcat。

这款插件操作简单，容易上手，能够让开发者省去API文档编写的工作，更专注于开发。插件通过分析用户注释进行接口解析，最终生成接口文档并上传至 Postcat 服务器，使得开发者可以在 Postcat 上进行 API 管理和分享，提高协作能力和开发速度。

 

和Swagger 有什么区别呢？

Postcat 插件不会入侵到代码内部，无需添加任何jar包依赖

插件通过分析用户注释进行接口解析，最终生成接口文档并上传至 Postcat 服务器，使得开发者可以在 Postcat 上进行 API 管理和分享，提高协作能力和开发速度。

Postcat 提供了多种拓展注释，如@path、@url、@method、@name、@hidden和@required，这些注释可以在设置界面进行自定义或兼容现有注释。

此外，Postcat 还提供了注释生成功能，对于没有或仅有少量注释的类和方法，开发者无需费力手动添加，该功能可以分析方法字段含义并自动生成注释。开发者只需要检查或根据实际场景进行微调，即可生成一份较完善的API文档。

如果原有注释不足，Postcat 会通过添加方式补充注释，移除注释时只会移除Postcat提供的那些拓展性注释，不会破坏用户自身的注释。同时，开发者还可以使用"意图"功能局部生成插件注释，并进行调整和修改。

Postcat提供了多种 API 上传方式，方便开发者在不同的场景下使用：

对于首次使用Postcat的现有项目，开发者可以使用主菜单中Tools分组下的Upload Project Api Doc来完成项目级别的接口上传。

对于新需求下创建的Controller，在完成接口定义后，开发者可以右键菜单，选择 Upload All Api 来进行单个文件级别全部上传，做到先有文档再有逻辑，前后端工作不再串行阻塞。

对于某个部分单独接口的改动，无需全部上传，开发者可以右键菜单，选择Upload Api功能，该功能会展示当前编辑类的接口信息，并提供接口预览和接口选择界面，使得用户可以勾选需要更新或上传的目标API进行信息核对和上传。

如何安装配置？

IDEA 版本需大于 IntelliJ IDEA 2023.03

在 IDEA “设置-插件-Marketplace” 中搜索 Postcat，找到 Postcat 插件安装即可。同时也可在IDEA插件市场上进行下载安装，本地的IDEA没有自动唤起时，可以直接把zip包拖入IDEA中即可完成安装/更新。

填写配置信息

首次上传需要填写配置信息，配置信息项目之间独立。

配置信息获取途径：登陆 Postcat 进入项目中获取 Token、WorkspaceID 和 ProjectID。

Server 默认填写：https://postcat.com/api， 用户无需修改

Token获取

 

WorkspaceID 和 ProjectID 获取

 

进入项目设置页面，点击项目名右侧“问号”

StringType 决定出入参的字符串类型，只有参数名一开始就是遵守驼峰规范才会发现改变，预览窗口可看到变化结果

1. 当参数名为userInfo，选择 camelCase，依旧是userInfo，这是默认选项

2. 当参数名为userInfo，选择 lower_underscore，会变成user_info

3. 当参数名为userInfo，选择 UPPER_UNDERSCORE，会变成USER_INFO  

注意事项

进行解析上传前，请确保 IDEA 在项目中已经构建完，相关依赖已经下载好。

强烈推荐使用插件定义的注释，插件有强大的生成注释功能，强烈建议先生成插件的注释进行编辑再上传，注释可以在设置也进行自定义。

在识别不到插件注释时，仅对Spring MVC、Swagger.v2和Swagger(OpenAPI).v3的注解只做部分简单支持。为避免必要参数的缺失，推荐使用插件注释。

生成注释功能会对Spring MVC、Swagger.v2 和Swagger(OpenAPI).v3的注解只做部分简单支持，而不会让你重头编写。

HTTP接口通过路由和请求方式判断唯一做覆盖更新处理

对于已经上传的 API，在 web 上进行过手动修改，不建议再使用上传功能，因为插件上传会覆盖掉之前的内容。

在生成/手敲了插件javadoc后，对接口uri，请求方式（GET/POST）等做了修改，需要手动修改插件javadoc，否则插件还是会识别到旧的插件javadoc信息。

自动生成的类注释默认会上传到默认分组，请用户自行填写真实的分组，分组通过名字识别。

如多级分组，则用.隔开，比如需要把接口传到第三方分组下的用户分组，则 group-name 填写 第三方.用户。

@group-name注释 支持到方法级别，默认不生成，可手动添加到方法注释，插件会帮你将当前方法存到对应分组中。

项目级别的 api 扫描和上传，顶部菜单[Tools -> Upload Project Api Doc]，具体使用规则看 项目级上传。

生成类注释不在默认生成@required注释，只会针对有javax.validation.constraints.NotNull注解的字段才生成。

不推荐使用@remark注释，插件保留了识别功能且将内容拼接到字段说明中，生成类注释不会自动生成。

通过@PathVariable，POST方法默认把参数识别成 Formdata 类型，GET方法默认把参数识别成 query 类型。

//标识的注释无法被识别出来，请使用/** */标识。

了解 Postcat：

Postcat 是一个强大的开源、跨平台（Windows、Mac、Linux、Browsers...）的 API 开发测试工具，支持 REST、Websocket 等协议（即将支持 GraphQL、gRPC、TCP、UDP），帮助你加速完成 API 开发和测试工作。

 

Postcat 核心功能：

API 文档管理，可视化 API 设计，生成 API 文档

API 测试， 自动生成测试参数，自动生成测试用例，可视化数据编辑

Mock，根据文档自动生成Mock,或创建自定义 Mock 满足复杂场景

插件拓展，众多插件扩展产品功能，打造属于你和团队的 API 开发平台

团队协作，既能实现API 分享也能可以创建云空间共同协作

如果喜欢，不妨 Star 支持一下

这个项目是开源的，如果你觉得这个项目还不错的话，不妨点个 Star 支持一下！ Github ：https://github.com/Postcatlab/postcat