PostIn入门教程 - 使用IDEA插件快速生成API接口定义-海口c网

PostIn入门教程 - 使用IDEA插件快速生成API接口定义

article/2025/6/21 6:33:04

PostIn是一款国产开源免费的接口管理工具，包含项目管理、接口调试、接口文档设计、接口数据MOCK等模块，支持常见的HTTP协议、websocket协议等。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：请求参数内容。