 - 使用IDEA插件快速生成API接口定义)
PostIn是一款开源免费的接口管理工具，包含项目管理、接口调试、接口文档设计、接口数据MOCK等模块。IDEA插件可扫描代码自动生成接口文档并上传到PostIn系统。本文将详细介绍怎么安装IDEA插件，使用插件上报接口并生成接口文档。
1、插件下载及安装
本节将详细介绍 PostIn 插件下载、安装。
方式1：在 IntelliJ IDEA 中搜索并安装 PostIn 插件。
打开 IDEA 设置，进入 Plugins（插件）页面，搜索 “PostIn” 并安装 “PostIn” 插件。
安装插件
方式2：在 Jetbrains Marketplace 中下载后通过本地安装，下载地址：IDEA插件。
打开 IDEA 设置，进入 Plugins（插件）页面，点击Installed右侧的设置按钮，选择"install plugin from disk... "，从磁盘安装插件。注意：插件仅支持 IntelliJ IDEA 2024.1.7 版本。
本地安装插件
安装结束后，在idea右侧侧边栏显示PostIn。
IDEA插件界面
2、插件配置
IDEA安装结束后，要对插件进行配置。
进入插件后，显示扫描接口， 上报接口，设置三个按钮。
功能说明
配置PostIn插件，点击“设置”按钮，进入PostIn插件的配置。
插件配置
需要配置PostIn服务的URL（注意配置的URL尾部不需要带"/"），以及上报接口的所属空间ID，上报接口的所属空间ID可以在PostIn空间详情。
项目信息
3、插件使用
IDEA插件配置结束后，使用插件之前，需要对代码中的接口进行注释，IDEA根据注释将接口上报到PostIn系统。
3.1 添加代码注释
首先需要在接口文件controller 中添加注释，包含接口协议、导入接口文件夹名称、接口地址。
/** * @pi.protocol: http * @pi.groupName: 空间关注 * @pi.path:/workspaceFollow */
● @pi.protocol：定义了接口的协议。
● @pi.groupName：定义了接口的文件夹名称。
● @pi.path：定义了该接口的基本 URL 路径。
其次，需要在接口前添加接口详细信息的注释，包含接口名称、接口详细URL、请求方式、请求类型、请求参数。通过请求类型的不同，可以分为两种。
第一种：模型
/** * @pi.name:创建空间关注123 * @pi.url:/createWorkspaceFollow * @pi.methodType:post * @pi.request-type:json * @pi.param: model=io.tiklab.postin.workspace.model.WorkspaceFollow */
● @pi.name：定义了接口的名称。
● @pi.url：和@pi.path共同组成了接口的完整路径，举例接口的完整路径：/workspaceFollow/createWorkspaceFollow
● @pi.methodType：定义了接口请求方式。
● @pi.request-type：定义了接口请求类型。
● @pi.param：请求参数内容。
接口注释
第二种：字段
/** * @pi.name:删除空间关注123 * @pi.url:/deleteWorkspaceFollow * @pi.methodType:post * @pi.request-type:formdata * @pi.param: name=id;dataType=string;value=workspaceId;desc=当前删除的id * @pi.param: name=id2;dataType=string;value=workspaceId2;desc=当前删除的id2 */
● @pi.name：定义了接口的名称。
● @pi.url：和@pi.path共同组成了接口的完整路径，举例接口的完整路径：/workspaceFollow/deleteWorkspaceFollow
● @pi.methodType：定义了接口请求方式。
● @pi.request-type：定义了接口请求类型。
● @pi.param：请求参数内容。
接口注释
3.2 扫描并上传API接口
注释添加完成后，在PostIn插件点击“扫描接口”按钮，扫描当前项目所有接口。
扫描接口
扫描出接口后，用户可单选、多选或全选接口后提交上报。例如，接口总共有7个，按Ctrl选择其中3个，点击“上传接口”按钮，系统弹出”确认上传接口“二次确认弹窗。
上报确认
点击“是”，选择的接口上传到PostIn系统。
成功上报
3.2 更新API文档
当接口进行更新之后，还可以利用PostIn插件对接口进行更新。
接口成功上传PostIn后，对接口信息进行修改，只要接口路径（即@pi.path和@pi.url组成的路径）未进行修改，再次上传接口，会对当前接口进行更新。
更新接口
接口路径（即@pi.path和@pi.url组成的路径）修改之后，再次上传接口，接口会按照新接口进行添加。
上报成功之后，可以在PostIn和 IntelliJ IDEA 环境信息对比。
上报接口对比
下图为请求为字段，上报PostIn前后信息对比。
上报接口对比
