乐趣区

关于api:IDEA-插件上新-生成接口文档就是这么快

jiezi

当有接口对接需要的时候，开发终于不必再放心 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. 填写配置信息

首次上传须要填写配置信息，配置信息我的项目之间独立。
配置信息获取路径：登陆 Postcat 进入我的项目中获取 Token、WorkspaceID 和 ProjectID。

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

  3. WorkspaceID 和 ProjectID 获取

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

  1. StringType 决定出入参的字符串类型，只有参数名一开始就是恪守驼峰标准才会发现扭转，预览窗口可看到变动后果

    1. 当参数名为 userInfo，抉择 camelCase，仍旧是 userInfo，这是默认选项
    2. 当参数名为 userInfo，抉择 lower_underscore，会变成 user_info
    3. 当参数名为 userInfo，抉择 UPPER_UNDERSCORE，会变成 USER_INFO

2. 注意事项

  1. 进行解析上传前，请确保 IDEA 在我的项目中曾经构建完，相干依赖曾经下载好。
  2. 强烈推荐应用插件定义的正文，插件有弱小的生成正文性能，强烈建议学生成插件的正文进行编辑再上传，正文能够在设置也进行自定义。
  3. 在辨认不到插件正文时，仅对 Spring MVC、Swagger.v2 和 Swagger(OpenAPI).v3 的注解只做局部简略反对。为防止必要参数的缺失，举荐应用插件正文。
  4. 生成正文性能会对 Spring MVC、Swagger.v2 和 Swagger(OpenAPI).v3 的注解只做局部简略反对，而不会让你重头编写。
  5. HTTP 接口通过路由和申请形式判断惟一做笼罩更新解决
  6. 对于曾经上传的 API，在 web 上进行过手动批改，不倡议再应用上传性能，因为插件上传会笼罩掉之前的内容。
  7. 在生成 / 手敲了插件 javadoc 后，对接口 uri，申请形式（GET/POST）等做了批改，须要手动批改插件 javadoc，否则插件还是会辨认到旧的插件 javadoc 信息。

  8. 主动生成的类正文默认会上传到默认分组，请用户自行填写实在的分组，分组通过名字辨认。

    1. 如多级分组，则用. 隔开，比方须要把接口传到第三方分组下的用户分组，则 group-name 填写 第三方. 用户。
  9. @group-name 正文 反对到办法级别，默认不生成，可手动增加到办法正文，插件会帮你将以后办法存到对应分组中。
  10. 我的项目级别的 api 扫描和上传，顶部菜单[Tools -> Upload Project Api Doc]，具体应用规定看 我的项目级上传。
  11. 生成类正文不在默认生成 @required 正文，只会针对有 javax.validation.constraints.NotNull 注解的字段才生成。
  12. 不举荐应用 @remark 正文，插件保留了辨认性能且将内容拼接到字段阐明中，生成类正文不会主动生成。
  13. 通过 @PathVariable，POST 办法默认把参数辨认成 Formdata 类型，GET 办法默认把参数辨认成 query 类型。
  14. // 标识的正文无奈被辨认进去，请应用 /* / 标识。

理解 Postcat：

Postcat 是一个弱小的开源、跨平台（Windows、Mac、Linux、Browsers…）的 API 开发测试工具，反对 REST、Websocket 等协定（行将反对 GraphQL、gRPC、TCP、UDP），帮忙你减速实现 API 开发和测试工作。

Postcat 外围性能：

  1. API 文档治理，可视化 API 设计，生成 API 文档
  2. API 测试，主动生成测试参数，主动生成测试用例，可视化数据编辑
  3. Mock，依据文档主动生成 Mock, 或创立自定义 Mock 满足简单场景
  4. 插件拓展，泛滥插件扩大产品性能，打造属于你和团队的 API 开发平台
  5. 团队合作，既能实现 API 分享也能能够创立云空间独特合作

如果喜爱，无妨 Star 反对一下

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

退出移动版