DSH API Spec Studio（OpenAPI 剖析台）

独立的 AI 原生产品：粘贴 OpenAPI/Swagger 规范 JSON，即刻校验结构问题（error/warn 分级）、列出端点清单、对比两版规范揪出破坏性变更、按标签检索、生成 mock 调用提示（参数/请求体/curl 草稿——只是文本，从不真实调用）。

深度集成为 DSH（deepseek-harness-java）Java Native Plugin 生态的独立 AI 产品案例之一（Batch 2 #3）。

功能

• 规范加载：OpenAPI 3.x / Swagger 2.x，内存保存，可加载多份做对比
• 规范校验：缺失 info/version/responses、operationId 缺失、path 格式等，error/warn 分级
• 端点清单：method/path/operationId/summary/tags/参数数/废弃标记
• 破坏性变更对比：端点删除、deprecated、请求体新增必填字段、新增必填参数、响应码删除——breaking/addition 分级
• 按 tag 检索：业务域视角筛端点
• Mock 提示：参数清单（in/name/type/required/enum）、请求体必填字段、示例值、curl 草稿
• AI 追问：SSE 流式对话，前端自动带上当前 specId 上下文，AI 强制调工具查证

工具（DSH Java Native Plugin）

插件 ID：dsh-java-api-plugin，工具前缀 api_：

工具	说明
api_spec_load	加载规范 JSON（唯一写入型）
api_spec_validate	规范校验（分级问题清单）
api_list_endpoints	端点清单（可按 tag 过滤）
api_diff_specs	两版规范破坏性变更对比
api_find_by_tag	按标签检索端点
api_mock_hint	mock 调用提示 + curl 草稿

快速开始

mvn package -DskipTests

SERVER__PORT= java -jar dsh-java-api-app/target/dsh-java-api-app-0.1.0-SNAPSHOT.jar --server.port=8094

cp dsh-java-api-plugin/target/dsh-java-api-plugin-0.1.0-SNAPSHOT.jar ~/.dsh/standalone/plugins/dsh-java-api-plugin.jar
curl --noproxy '*' -X POST http://127.0.0.1:8090/api/harness/plugins/install -H 'Content-Type: application/json' \
  -d '{"pluginId":"dsh-java-api-plugin","jarName":"dsh-java-api-plugin.jar","displayName":"dsh-java-api-plugin","pluginVersion":"0.1.0","runtimeType":"JAVA_NATIVE","sourcePath":"'"$HOME"'/.dsh/standalone/plugins/dsh-java-api-plugin.jar","entrypoint":"dsh-java-api-plugin.jar","installMode":"NATIVE"}'
curl --noproxy '*' -X POST http://127.0.0.1:8090/api/harness/plugins/activate -H 'Content-Type: application/json' -d '{"pluginId":"dsh-java-api-plugin"}'

打开 http://127.0.0.1:8094，「＋ 加载规范」粘贴 JSON 即可。

E2E 测试

前置：app 已启动（8094）、harness 已启动（8090）、插件已安装激活。

python3 api_spec_e2e.py
# 8/8 PASS：双规范加载 / 校验 / 端点清单 / tag 检索 / 破坏性变更对比 / mock 提示 / AI 工具调用 / 非法 JSON 拒绝

截图

场景	图
首页 + 校验面板
AI 追问（列出端点 + 破坏性变更，红线声明）
端点清单面板

安全边界（红线）

• 不修改规范文件、不发起真实 HTTP 调用（curl 仅草稿文本）
• AI 端点与字段信息只引用工具结果，未加载规范时提示先加载
• 规范数据仅在本机

技术

Java 17 · Spring Boot 3.3 · DSH Java Native Plugin（AbstractHarnessPlugin）· Jackson JsonNode 解析 · SSE 流式 · 端口 8094