接口文档使用指南(EOLINK)

接口文档统一在 EOLINK(空间 hiapi-cloud,项目 SaaS)。本仓库不存接口详情,只存本指南。

人:怎么看/怎么联调

1. 找管理员开通 EOLINK 空间成员
2. 网页端看文档、在线调试、Mock
3. 环境地址:dev 网关 http://192.168.50.3:8080

AI:怎么让你的 Claude Code 查接口

在你的项目配置 EOLINK MCP(token 用自己的,到 EOLINK 设置→个人令牌生成):

{
  "mcpServers": {
    "apikit-api-docs": {
      "type": "streamable-http",
      "url": "https://api.eolink.com/apikit/py-server/apikit-mcp",
      "headers": {
        "X-Access-Token": "<你的个人令牌>",
        "X-Space-ID": "hiapi-cloud"
      }
    }
  }
}

之后可以直接问 AI:"创建商户的接口怎么调"、"设备分页查询有哪些参数"——AI 会经 MCP 实时查 EOLINK。

文档从哪来(同步流水线)

接口文档的唯一真源是代码里的 Javadoc 注释,EOLINK 上不手工编辑接口。

Java 代码(实体/VO/Controller 写 Javadoc 注释)
   → 生成 OpenAPI(含 schema + 中文字段说明)
   → 经 EOLINK MCP import_api 导入(增量,按 URL+Method 去重)

约定:

• 改了接口 = 重新同步,在 PR 检查项里勾选
• 实体/VO 字段没写注释的接口,文档里字段说明就是空的——写注释是硬要求,见后端规范
• 接口分三类受众:对内(merchant/channel/platform/feign)、对外(user)、开放(open-api),在 EOLINK 内按分组管理

常见问题

• 接口在代码里有、EOLINK 没有? → 还没同步,找该服务 Owner 跑同步,或自己发起
• 字段说明是空的? → 源码里没写 Javadoc,补注释后重新同步
• 要新接口但对方还没做? → 走契约先行流程