OpenAPI

OpenAPI 模块提供平台对外开放的 API 接口，允许外部系统通过 REST API 访问平台数据和功能，实现系统集成和数据互通。

概述

OpenAPI 是 Chameleon 平台与外部系统集成的桥梁。通过标准化的 REST API，外部系统可以：

数据访问：读取和写入平台数据
元数据查询：获取实体和字段定义
业务流程：触发审批等业务流程
系统集成：与第三方系统对接

OpenAPI 的核心价值

标准化接口：统一的 API 规范，易于集成
安全认证：Token 认证机制，保障数据安全
完整文档：自动生成 API 文档
灵活控制：接口权限精细控制

接口认证

OpenAPI 接口需要通过 Token 进行身份认证。根据调用方式不同，Token 的获取方式也有所区别。

前端直接调用

前端可以直接使用当前登录用户的 Token 调用 OpenAPI：

Authorization: Bearer YOUR_USER_TOKEN

说明：

用户 Token 在前端登录后自动获取，无需手动处理
Token 会自动包含在请求头中
无需手动刷新，系统会自动处理 Token 更新

通过 SDK 调用

在微服务或脚本中，推荐使用 ChameleonSDK 提供的 OpenApiHelper 来调用 OpenAPI，SDK 内部会自动处理 Token 的获取和认证。

使用示例

using Chameleon.SDK;

public class ChameleonCSharpScript
{
    public async Task<object> ExecuteAsync(ComponentContext context, ChameleonSDK sdk)
    {
        // SDK 会自动处理 Token 认证
        var result = await sdk.OpenApiHelper.PostAsync<ResponseResult>(
            "api/OpenApi/Account/AssignProfile",
            new { profileId = "xxx", userIds = new[] { "userId1", "userId2" } }
        );

        return result;
    }
}

Token 处理机制

SDK 内部会根据配置自动选择合适的 Token：

主要接口

测试接口

接口	方法	说明
/api/OpenApi/Hello	POST	测试API连通性

账户管理接口

接口	方法	说明
/api/OpenApi/Account/AssignProfile	POST	批量为人员授予身份
/api/OpenApi/Account/RemoveProfile	POST	批量移除人员身份
/api/OpenApi/Account/AssignRole	POST	批量为人员授予角色
/api/OpenApi/Account/RemoveRole	POST	批量移除人员角色
/api/OpenApi/Account/GetUserIdsByProfileIds	POST	获取具有某些身份的人员ID集合
/api/OpenApi/Account/GetUserIdsByRoleIds	POST	获取具有某些角色的人员ID集合
/api/OpenApi/Account/GetUserProfileIds	POST	获取人员具有的身份ID集合
/api/OpenApi/Account/GetUsersProfileIds	POST	批量获取某些人具有的身份ID集合
/api/OpenApi/Account/GetUserRoleIds	POST	获取人员具有的角色ID集合
/api/OpenApi/Account/GetUsersRoleIds	POST	批量获取某些人具有的角色ID集合

通知接口

接口	方法	说明
/api/OpenApi/Notification/Notify	POST	发送通知

人员信息接口

接口	方法	说明
/api/OpenApi/UserInformation/BatchAddUserInformations	POST	批量添加人员信息
/api/OpenApi/UserInformation/BatchEditUserInformations	POST	批量编辑人员信息

审批流接口

接口	方法	说明
/api/OpenApi/Workflow/Launch	POST	发起审批
/api/OpenApi/Workflow/Agree	POST	同意审批
/api/OpenApi/Workflow/Disagree	POST	拒绝审批
/api/OpenApi/Workflow/Return	POST	撤回审批
/api/OpenApi/Workflow/Revoke	POST	驳回审批
/api/OpenApi/Workflow/GetCurrentUserInProgressDataIdList	POST	获取当前用户进行中的数据ID列表
/api/OpenApi/Workflow/GetCurrentUserParticipatedDataIdList	POST	获取当前用户参与的数据ID列表
/api/OpenApi/Workflow/GetUserPendingApprovalList	POST	获取指定用户待审核的审批列表
/api/OpenApi/Workflow/GetUserParticipatedApprovalList	POST	获取指定用户参与过的审批列表

定时任务接口

接口	方法	说明
/api/OpenApi/ScheduleJob/Create	POST	创建定时任务（创建即为启用状态）
/api/OpenApi/ScheduleJob/Edit	POST	编辑定时任务
/api/OpenApi/ScheduleJob/Enable	POST	启用定时任务
/api/OpenApi/ScheduleJob/Disable	POST	停用定时任务
/api/OpenApi/ScheduleJob/Delete	POST	删除定时任务
/api/OpenApi/ScheduleJob/Get	POST	根据 ID 查询定时任务定义

请求示例

测试API连通性

curl -X POST "https://api.example.com/api/OpenApi/Hello" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

响应示例：

{
    "success": true,
    "data": "This is chameleon test API, tenant: xxx, userId: xxx",
    "errorCode": 0,
    "errorMessage": ""
}

为人员授予身份

curl -X POST "https://api.example.com/api/OpenApi/Account/AssignProfile" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "身份ID",
    "userIds": ["用户ID1", "用户ID2"]
  }'

发送通知

curl -X POST "https://api.example.com/api/OpenApi/Notification/Notify" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "userId": "用户ID",
      "title": "通知标题",
      "content": "通知内容"
    }
  ]'

批量添加人员

curl -X POST "https://api.example.com/api/OpenApi/UserInformation/BatchAddUserInformations" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "list": [
      {
        "name": "张三",
        "number": "001",
        "email": "zhangsan@example.com"
      }
    ]
  }'

发起审批

curl -X POST "https://api.example.com/api/OpenApi/Workflow/Launch" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metaObjectCode": "实体编码",
    "bizDataId": "业务数据ID",
    "workflowId": "审批流ID",
    "launchUserId": "发起人ID"
  }'

获取指定用户待审核的审批列表

curl -X POST "https://api.example.com/api/OpenApi/Workflow/GetUserPendingApprovalList" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "UserId": "用户ID",
    "Condition": {
      "Field": "metaobjectcode",
      "Operator": "Eq",
      "Value": "LeaveApplication"
    }
  }'

参数说明：

参数	类型	说明
UserId	string	要查询的用户 ID（必填）
Condition	DynamicFilter	可选过滤条件，格式见查询操作符说明，后台会将其与固定条件（待审核：`status=进行中` 且 `pendingapproveruserids` 包含该用户）合并

响应示例：

{
    "data": [
        {
            "InstanceId": "流程实例ID",
            "BizDataId": "业务数据ID",
            "MetaObjectCode": "LeaveApplication",
            "WorkflowId": "流程ID",
            "WorkflowTitle": "请假审批",
            "NodeTitle": "直属主管审批",
            "LaunchUserId": "发起人ID",
            "LaunchUserDisplay": "张三",
            "Status": 1,
            "CurrentNode": "节点ID",
            "MetaPageId": "页面ID",
            "EntryTime": "2026-08-23T10:00:00Z",
            "LaunchDateTime": "2026-08-23T09:00:00Z",
            "FinishedTime": null
        }
    ],
    "total": 1,
    "code": 200,
    "message": "操作成功"
}

获取指定用户参与过的审批列表

请求体结构同上（UserId + Condition），固定条件为 participantuserids 包含该用户，不限制审批状态：

curl -X POST "https://api.example.com/api/OpenApi/Workflow/GetUserParticipatedApprovalList" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "UserId": "用户ID"
  }'

响应格式

OpenAPI 接口统一使用 ResponseResult 模型返回数据。

成功响应

{
    "data": {
        "items": [...],
        "total": 100
    },
    "total": 100,
    "action": 0,
    "code": 200,
    "message": "操作成功",
    "moreMessage": null,
    "duration": 0,
    "popType": 0,
    "placement": 0,
    "redirectUrl": null,
    "traceId": "trace-id-xxx"
}

错误响应

平台的业务级错误统一返回 code: 510，错误详情在 message 和 moreMessage 字段中提供：

{
    "data": null,
    "total": 0,
    "action": 1,
    "code": 510,
    "message": "操作失败",
    "moreMessage": "详细错误信息，例如：Token 无效或已过期",
    "duration": 0,
    "popType": 0,
    "placement": 0,
    "redirectUrl": null,
    "traceId": "trace-id-xxx"
}

响应字段说明

字段	类型	说明
data	object	返回的数据内容
total	int	数据总数（列表查询时有效）
action	int	操作类型：0=成功，1=失败，2=警告，3=信息，4=重定向，5=打开新地址
code	int	状态码：200=成功，510=业务错误
message	string	提示消息
moreMessage	string	更多消息（详细错误信息）
duration	int	消息提示关闭时间（毫秒）
popType	int	消息提示方式：0=系统默认，1=提示，2=通知
placement	int	通知弹出位置：0=系统默认，1=上，2=左上，3=右上，4=下，5=左下，6=右下
redirectUrl	string	重定向或新打开的 URL 地址
traceId	string	请求追踪ID

常见错误示例

参数错误：

{
    "code": 510,
    "action": 1,
    "message": "参数错误",
    "moreMessage": "必填参数 userId 不能为空"
}

权限不足：

{
    "code": 510,
    "action": 1,
    "message": "权限不足",
    "moreMessage": "您没有执行此操作的权限"
}

资源不存在：

{
    "code": 510,
    "action": 1,
    "message": "资源不存在",
    "moreMessage": "指定的数据记录不存在"
}

更多消息提示配置，请参考消息提示定义。

接口权限

权限配置

为 API 客户端配置访问权限：

权限类型	说明
实体权限	可访问的实体对象
操作权限	可执行的操作类型
数据权限	可访问的数据范围

权限验证

每次 API 请求都会验证权限：

验证 Token 有效性
验证接口访问权限
验证数据访问权限

API 文档

平台内置 Swagger 在线文档页面，从 开发中心 → 开发设置 → OpenAPI 文档 进入，以内嵌 Swagger UI 的方式在线展示服务端生成的 OpenAPI 规范（swagger.json），便于查阅接口路径、参数与响应结构。

页面特性：

特性	说明
接口分组	按控制器分组展示全部开放接口
模型定义	隐藏模型明细区块，聚焦接口本身
只读浏览	不支持在页面上直接发起「Try it out」请求
自动鉴权	请求会携带当前登录用户的 Token（`Authorization: Bearer {token}`）

每个接口文档包含接口地址与方法、请求参数说明、响应格式说明、错误码说明与示例代码。

使用场景：查阅某个开放接口的路径、方法与参数结构；对照接口定义编写第三方系统或脚本的调用代码；在校验接口契约时快速定位接口。

渲染配置

页面通过 swagger-ui-react 组件渲染，关键配置如下：

配置项	取值	含义
`url`	`{serverHost}/swagger/open/swagger.json`	OpenAPI 规范地址，由 `helper.getServerHost('/swagger/open/swagger.json')` 生成
`docExpansion`	`list`	默认展开方式为「按分组列出」
`supportedSubmitMethods`	`[]`	禁用全部「Try it out」提交方法，页面仅用于浏览
`defaultModelsExpandDepth`	`-1`	折叠模型定义区块
`requestInterceptor`	注入 `Authorization`	`req.headers['Authorization'] = 'Bearer ' + helper.getToken()`

规范地址

Swagger 规范由服务端生成并可公开访问：/swagger/open/swagger.json；页面中的实际地址会拼接当前服务的 Host。

最佳实践

安全建议

妥善保管 Client ID 和 Client Secret
使用 HTTPS 加密传输
定期刷新 Token
设置合理的 Token 过期时间

性能优化

使用批量接口减少请求次数
合理设置分页大小
只查询需要的字段
使用缓存减少重复请求

错误处理

处理 Token 过期自动刷新
实现请求重试机制
记录错误日志便于排查

下一步

租户配置文件 - 租户级配置
平台接口 - 配置业务接口

概述​

OpenAPI 的核心价值​

接口认证​

前端直接调用​

通过 SDK 调用​

使用示例​

Token 处理机制​

主要接口​

测试接口​

账户管理接口​

通知接口​

人员信息接口​

审批流接口​

定时任务接口​

请求示例​

测试API连通性​

为人员授予身份​

发送通知​

批量添加人员​

发起审批​

获取指定用户待审核的审批列表​

获取指定用户参与过的审批列表​

响应格式​

成功响应​

错误响应​

响应字段说明​

常见错误示例​

接口权限​

权限配置​

权限验证​

API 文档​

渲染配置​

最佳实践​

安全建议​

性能优化​

错误处理​

下一步​

概述