当有接口对接需求的时候，开发终于不用再担心 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 2022.03

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

1. 填写配置信息
   

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

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

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

3.WorkspaceID 和 ProjectID 获取

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

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

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

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

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

2. 
   
3. 
   
4. 注意事项
   
5. 1. 进行解析上传前，请确保 IDEA 在项目中已经构建完，相关依赖已经下载好。
   
6. 2. 强烈推荐使用插件定义的注释，插件有强大的生成注释功能，强烈建议先生成插件的注释进行编辑再上传，注释可以在设置也进行自定义。
   
7. 3. 在识别不到插件注释时，仅对Spring MVC、Swagger.v2和Swagger(OpenAPI).v3的注解只做部分简单支持。为避免必要参数的缺失，推荐使用插件注释。
   
8. 4. 生成注释功能会对Spring MVC、Swagger.v2 和Swagger(OpenAPI).v3的注解只做部分简单支持，而不会让你重头编写。
9. 5.
10. HTTP接口通过路由和请求方式判断唯一做覆盖更新处理
    
11. 6.  对于已经上传的 API，在 web 上进行过手动修改，不建议再使用上传功能，因为插件上传会覆盖掉之前的内容。
    
12. 7. 在生成/手敲了插件javadoc后，对接口uri，请求方式（GET/POST）等做了修改，需要手动修改插件javadoc，否则插件还是会识别到旧的插件javadoc信息。
    
13. 8. 自动生成的类注释默认会上传到默认分组，请用户自行填写真实的分组，分组通过名字识别。

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

14. 9.
15. @group-name注释 支持到方法级别，默认不生成，可手动添加到方法注释，插件会帮你将当前方法存到对应分组中。
    
16. 10. 项目级别的 api 扫描和上传，顶部菜单[Tools -> Upload Project Api Doc]，具体使用规则看 项目级上传。
    
17. 11. 生成类注释不在默认生成@required注释，只会针对有javax.validation.constraints.NotNull注解的字段才生成。
    
18. 12. 不推荐使用@remark注释，插件保留了识别功能且将内容拼接到字段说明中，生成类注释不会自动生成。
    
19. 13. 通过@PathVariable，POST方法默认把参数识别成 Formdata 类型，GET方法默认把参数识别成 query 类型。
20. 14.
21. //标识的注释无法被识别出来，请使用/** */标识。  
    

了解 Postcat：

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

Postcat 核心功能：

• API 文档管理：可视化 API 设计，生成 API 文档
  
• API 测试：自动生成测试参数，自动生成测试用例，可视化数据编辑
  
• 插件拓展：众多插件扩展产品功能，打造属于你和团队的 API 开发平台
  
• Mock：根据文档自动生成 Mock,或创建自定义 Mock 满足复杂场景
  
• 团队协作：既能实现 API 分享也能可以创建云空间共同协作
  

Postcat 优势：

• 免登录即可测试：省去繁琐的验证登录的操作
  
• 界面简洁：没有冗余的功能与复杂选项
  
• 免费：中小团队以及个人使用
  
• 丰富的插件：支持数据迁移、主题、API 安全等高达 25 款插件
  
• 国产：能更好的理解国内用户的需求，与开发团队沟通无障碍
  
• 完善的用户文档：跟着操作就能快速上手
  

多提 Issue !多反馈！

在使用过程中有任何疑问，可以进群交流，也可以在线提 Issue（强烈推荐这种开源的方式），提问题本身就已经在贡献社区了：https://github.com/Postcatlab/postcat/issues

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

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