`RestApiSkill` 是 Solon AI 生态中连接“大模型意图”与“传统 REST 服务”的智能桥梁。它能够自动解析 OpenAPI (Swagger) 定义，并将其转化为 AI 智能体（Agent）可理解、可调用的结构化技能。提供渐进式加载支持。

此技能，可以很好的激活海量现有 WebApi


相关依赖包： [solon-ai-skill-restapi](/article/1364)


### 1、核心特性

* 多源 API 整合：支持从多个不同的 Swagger 节点（http 或 classpath）并行加载接口。
* 三阶段动态发现：内置阈值切换机制，自动解决接口过多导致的 Token 溢出问题。
* 全自动代理：AI 仅需下达意图，由网关自动完成 Path 替换、Query/Body 序列化及 Header 注入。
* 上下文保护：内置响应结果截断（默认 8000 字符），防止庞大的业务数据撑爆 AI 上下文。


### 2、应用示例

通过以下配置，你可以让智能体瞬间具备操作多个微服务系统的能力：

```java
// 1. 初始化 Skill
RestApiSkill apiSkill = new RestApiSkill()
        .dynamicThreshold(5)  // 超过 5 个接口开启清单模式
        .searchThreshold(50)  // 超过 50 个接口开启搜索模式
        .maxContextLength(10000) // 结果截断长度
        .defaultAuthenticator((http, tool) -> {
             http.header("Authorization", "Bearer your-token"); // 全局认证配置
        });

// 2. 挂载多个业务模块的 API (支持 http 或 本地资源)
apiSkill.addApi("http://order-service:8081/v3/api-docs", "http://order-service:8081");
apiSkill.addApi("classpath:swagger/user-api.json", "http://user-service:8082");

// 3. 构建智能体
ReActAgent agent = ReActAgent.of(LlmUtil.getChatModel())
        .role("高级业务助理")
        .instruction("请优先使用提供的业务 API 解决问题，不要猜测接口参数。")
        .defaultSkillAdd(apiSkill)
        .build();

// 4. 自然语言触发（Agent 会自动选择 search_apis -> get_api_detail -> call_api 流程）
agent.prompt("查询张三名下的所有订单，并告诉我最近一笔的物流状态。");
```


### 3、三阶段动态发现机制

为了平衡“易用性”与“Token 成本”，RestApiSkill 会根据接口总数自动切换模式：



| 模式名称 | 触发阈值 | 对 LLM 的表现 | 机制说明 |
| -------- | -------- | -------- | -------- |
| FULL (全量)     | 数量 `<= 8`     | 直接看到所有接口定义     |  仅暴露 `call_api`。  |
| DYNAMIC (清单)     | `8 <` 数量 `<= 80`     | 看到接口名 + 功能简述清单     |  暴露 `get_api_detail` + `call_api`。  |
| SEARCH (搜索)     | 数量 `> 80`     | 接口清单折叠，需按需检索     |  暴露 `search_apis` + `get_api_detail` + `call_api`。  |


### 4、内置管理工具说明

AI 在处理任务时，会根据当前模式自动调用以下内部工具：

* `search_apis(keyword)`：在海量 API 库中通过多关键词（空格分隔）模糊搜索匹配的接口。
* `get_api_detail(api_name)`：获取指定接口的参数 Schema（含 Header, Path, Query, Body）及返回值定义。
* `call_api(...)`：执行调用。支持复杂的路径参数替换（如 `/user/{id}`）及多部分（Multipart）提交。

### 5、注意事项

* 接口唯一性：不同数据源加载的接口，其 OperationId (API 名称) 不能重复，网关会将其统一转为小写存储。
* 路径占位符：确保 Swagger 定义中的路径参数使用 {name} 格式，网关会自动完成 URLEncoder 编码替换。
* 过时接口：代码会自动忽略 Swagger 中标记为 @Deprecated 的接口，保持 Agent 技能树的整洁。