API 文档

本文档说明项目 API 文档与接口调用说明模块的使用约定。

技术方案

项目默认使用 spring-open-starter-openapi 提供 OpenAPI 元数据能力，底层基于 springdoc-openapi。

当前默认能力：

• OpenAPI 3.1 JSON：/v3/api-docs
• core 分组文档：/v3/api-docs/core
• Swagger UI：/swagger-ui.html
• Swagger UI 只约定使用 /swagger-ui.html，不要使用 /swagger-ui/ 作为访问入口。
• 统一 Bearer JWT 鉴权声明。
• 统一 Result<T> 和 Result<PageResult<T>> 响应 schema。
• AI Agent 友好的 OpenAPI extensions。

配置入口

spring:
  open:
    openapi:
      enabled: true
      title: ${APP_NAME:spring-open} API
      version: ${APP_VERSION:0.0.1}
      ai-metadata-enabled: true
      security:
        enabled: true
        scheme-name: bearerAuth
        header-name: Authorization
        bearer-format: JWT
      groups:
        - name: all
          paths-to-match:
            - /api/**
          packages-to-scan:
            - com.springopen
        - name: system
          display-name: System APIs
          paths-to-match:
            - /api/**
          packages-to-scan:
            - com.springopen.core

Controller 注解规范

普通 JSON 接口：

@Operation(operationId = "config__detail", summary = "查询配置项详情")
@ApiResult(ConfigVO.class)
public ResponseEntity<?> detail(...) {
    ...
}

分页 JSON 接口：

@Operation(operationId = "config__page", summary = "分页查询配置项")
@ApiPageResult(ConfigVO.class)
public ResponseEntity<?> page(...) {
    ...
}

无业务数据接口：

@Operation(operationId = "auth__logout", summary = "退出登录")
@ApiResult
public ResponseEntity<?> logout() {
    ...
}

公开接口：

@PublicApi
@Operation(operationId = "auth__login", summary = "账号密码登录")
@ApiResult(LoginVO.class)
public ResponseEntity<?> login(...) {
    ...
}

operationId 规范

operationId 必须稳定、可读、唯一，统一格式：

模块__动作

• 全小写 snake_case；模块段与动作段之间用双下划线 __ 作结构分隔，两段内部各用单下划线。
• 模块段是资源命名空间（可多词，如 reading_admin_source），动作段是操作（可多词，如 update_health、approve_manual_review）。
• 只允许 [a-z0-9_]，对 SDK / MCP tool 代码生成安全；不使用点号、连字符、camelCase。

示例：

• config__page
• config__detail
• auth__login
• iam_user__create
• reading_admin_source__update_health
• money_web3_bridge_admin_order__approve_manual_review

双下划线让「模块 / 动作」边界确定性可解析：操作日志审计（iam.md）据此还原 module / action，无需维护动作词表；多词动作不会被截断。稳定的 operationId 也会被后续 SDK 生成、AI Agent 接口识别、MCP Tool Calling 映射复用。

鉴权说明

默认鉴权方式：

Authorization: Bearer <token>

OpenAPI 中默认声明 bearerAuth。标记 @PublicApi 的接口不会附加默认鉴权要求。

AI Agent 元数据

OpenAPI 文档会补充扩展字段：

• x-ai-friendly-framework
• x-api-metadata-version
• x-result-code-source
• x-app-module
• x-controller
• x-auth-required
• x-result-wrapper

这些字段用于后续：

• AI Agent 自动理解接口。
• 生成 MCP tool metadata。
• 生成 TypeScript / Java SDK。
• 生成接口测试脚本。

面向 AI Agent、MCP 和第三方服务端调用的完整约定见 AI Agent 接入。

源码机制骨架

OpenAPI starter 的核心类位于 spring-open-starters/spring-open-starter-openapi：

类 / 注解	职责
OpenApiAutoConfiguration	自动装配 OpenAPI、统一响应定制器、全局 metadata customizer 和 API 分组
OpenApiProperties	绑定 spring.open.openapi.*，提供文档标题、版本、鉴权 scheme、AI metadata 和分组配置
OpenApiResultOperationCustomizer	根据 @ApiResult / @ApiPageResult / @ApiResourceResult / @PublicApi 补齐 operationId、tag、鉴权、AI metadata 和统一响应 schema
OpenApiSchemaRegistry	收集响应包装中引用过的 VO / DTO 类型，并统一写入 OpenAPI components，保证 $ref 可解析
OpenApiModuleContributor	业务模块贡献文档分组的扩展点，只描述扫描边界，不承担权限或业务开关

生成流程：

1. OpenApiAutoConfiguration 读取配置并创建基础 OpenAPI。
2. OpenApiResultOperationCustomizer 在每个 Controller operation 上补齐统一响应、鉴权和 AI metadata。
3. 被响应 schema 引用的模型先进入 OpenApiSchemaRegistry。
4. 全局 OpenApiCustomizer 最后把 registry 中的模型写入 components，并补充框架级 x-* 扩展。
5. 配置中的 groups 和模块贡献的 OpenApiModuleContributor 合并为最终分组文档。

扩展边界

• 新增业务模块分组：优先实现 OpenApiModuleContributor，不要在应用层重复声明 GroupedOpenApi。
• 新增普通 JSON contract：优先在 Controller 上使用 @ApiResult 或 @ApiPageResult。
• 新增资源型后台 Controller：可以在类型上使用 @ApiResourceResult，由常见 CRUD 方法名推导响应包装。
• 公开接口：使用 @PublicApi，OpenAPI 文档不会附加默认 Bearer 鉴权要求。
• 文件下载、SSE 和 WebSocket：不使用统一 Result<T> 注解强行包装，按对应协议文档维护。
• 权限、签名、调用配额和业务开关不在 OpenAPI starter 内实现，继续放在 Auth、Open Platform 或业务模块。

文件、SSE、WebSocket

普通 JSON 接口使用 @ApiResult 或 @ApiPageResult。

文件下载接口后续使用标准 OpenAPI application/octet-stream schema 描述，不使用 Result<T> 包装。

SSE 接口后续使用 text/event-stream 描述事件流，不使用普通 JSON schema。

WebSocket 不强塞到 OpenAPI 主模型；spring-open-starter-websocket 提供默认连接端点 /api/ws、用户绑定解析扩展点、握手拦截器接入、文本消息处理 SPI 和可选 Redisson Topic 多实例分发。正式聊天体验使用 Conversation 的 REST + WebSocket contract。消息协议先在正式 Conversation / WebSocket 文档中维护，后续如出现跨语言稳定消息契约，再评估 AsyncAPI 或独立消息契约文档。