“写完接口还要写文档”曾是庚商后端同学最头秃的环节。
需求三天一小改，接口五天一大改，Word、Postman、Swagger轮番上阵，版本仍永远对不齐。
直到我们统一引入JetBrains插件 Apipost-Helper，才真正实现“代码即文档，右键即交付”。今天把整套玩法公开，欢迎同行抄作业。

一、为什么是它？四个理由无法拒绝

1. 代码零入侵
   基于原生Java/Kotlin注释和Spring注解，无需额外@API、@ApiOperation，老项目插上就能用。
2. 一键上传
   在IDEA里右键 → Upload to Apipost，3秒生成在线文档，前端、测试、产品同时收到通知，零等待。
3. 内网可用
   公司禁用外网时切“游客模式”，接口数据离线缓存本地，回连后手动同步，安全合规。
4. 完全免费
   个人版、IDEA插件均0元，省去采购审批，IT部门直接放行。

二、30秒完成安装

1. 打开IDEA → Plugins → 搜索 Apipost-Helper → Install
2. 重启后右侧出现“Apipost”标签，登录或进入游客模式即可。
   官方地址先收藏：
   插件市场：https://plugins.jetbrains.com/plugin/22676-apipost-helper-2-0/versions
   图文指南：https://wiki.apipost.cn/docs/idea/helper_old

三、注释怎么写？两套规范直接抄

方案A：极简Javadoc——老项目无痛升级

入参：在@param后空格给示例

上传后Apipost自动解析为表格：字段、类型、示例、描述、是否必填，一个不落。

返回值：@return用“字段#类型#含义#示例”，多行以“|”分隔

插件会把整段拆成响应字段表，无需手写一行JSON示例。

方案B：SpringDoc+@Schema——新项目一步到位

引入依赖（已含swagger-annotations）

在DTO里一次性写全中文名、示例、是否必填：

Apipost-Helper识别后自动回填到“请求/响应参数”页签，彻底告别手写@return。

四、庚商团队落地规范——让10个人写得像1个人

1. 注释约定
   类头加@module 订单中心或@menu 库存管理，方法必须有一行summary，方便后续自动生成目录树。
2. 目录约定
   后端模块⇒Apipost一级目录；业务子域⇒二级目录；禁止把接口散落在根目录，测试批量勾选时一眼定位。
3. 上线Checklist
   代码Review通过→本地Upload→文档链接自动推送到企业微信群→前端确认后合并分支。
   从此“接口变更不同步”再也不是上线阻塞项。

五、结语

写代码不讨厌，写文档才讨厌。
当文档可以自己“长”出来，当同事之间不再需要发来发去的JSON，当内网也能离线调试，你就会发现：所谓“接口自由”，实则只是一个插件的距离。
庚商团队已全面拥抱Apipost-Helper，你的项目准备好了吗？右键Upload，让我们一起告别“接口对不齐”的昨天！

（注：本文原创为公众号《庚商开发开放平台》）