Appearance

API 文档 ​

本文说明 ecshopx-java 如何查阅与维护 API 文档，以及二次开发时的推荐做法。默认 API 基址：http://localhost:18080/api/（见 本地 / Docker 部署）。

接口文档来源 ​

业务 REST 接口以 Controller 路由 + 代码约定 为事实来源（见 路由与 API 分组）。仓库内未提供随应用启动的统一交互式 API 文档站，日常查阅请以下列方式为主。

日常如何查接口 ​

1. 读 Controller 源码（管理端 / C 端） ​

典型目录：

text
ecshopx-<domain>/src/main/java/cn/shopex/ecshopx/<domain>/api/
├── admin/v1/   # @RequestMapping("/api/v1/<资源域>")
└── front/v1/   # @RequestMapping("/api/v1/h5app/wxapp/...")

示例（商品域）：

端类前缀列表路径
管理端ecshopx-goods/.../api/admin/v1/ItemsController.java/api/v1/goodsGET /items
C 端ecshopx-goods/.../api/front/v1/ItemsController.java/api/v1/h5app/wxapp/goodsGET /items

部分路由在 @GetMapping / @PostMapping 上使用 name = "商品列表" 等 可读名称，便于检索。

本地验证 URL 示例见 快速入门 与 调试。

2. 开放 API（第三方对接） ​

对外 OpenAPI 网关集中在 ecshopx-openapi 模块，公共前缀 /api/openapi（详见 路由与 API 分组）。

签名与鉴权见 开放接口签名算法。

3. 协作工具（可选） ​

技术说明 提及团队可用 YApi 管理接口文档与 Mock；仓库内未内置 YApi 配置，按项目组自行维护。

二次开发：如何写清接口 ​

新增或修改 REST 接口时，应该：

  1. 遵循 API 控制器规范 与 路由约定；
  2. 在 @RequestMapping / @GetMapping 等注解上保持 资源化路径 与 name 中文说明（与现有 Controller 一致）；
  3. 复杂请求/响应字段在 Service 或 DTO 类上用必要注释说明业务含义；
  4. 跨模块能力走 Port，不在 Controller 堆叠实现细节（见 Controller）。

相关章节 ​