Swagger MCP 实战指南：如何用 Spring Boot + Spring AI 将 OpenAPI 封装...

在 AI Agent 与后端架构融合的浪潮中，如何让大模型安全、稳定地调用业务 API，始终是开发者面临的核心难题。本文将深入解析一种优雅的解决方案：通过 Spring Boot 与 Spring AI 构建 MCP（Model Context Protocol）服务，将传统的 OpenAPI 文档自动转化为大模型可直接使用的工具集，从而打通 AI 与微服务之间的最后一公里。

模块路径：
目标：将任意 OpenAPI/Swagger (3.x) 文档映射为 MCP 的 tools/resources/prompts，让大模型能安全、可控地调用后端接口。

Git 仓库： langchain4j-spring-agent/langchain4j-spring-ai/langchain4j-spring-ai-swagger-mcp

为什么需要 Swagger MCP？

在传统的 AI 集成方案中，大模型往往需要通过拼接 HTTP 请求来调用外部接口，这种方式不仅容易出错，而且难以管理与审计。Swagger MCP 的核心价值在于它彻底改变了这一局面：

接口能力规范化：将分散的 API 端点统一转化为 MCP tools，大模型不再需要猜测接口地址和参数格式，直接基于工具定义即可完成调用。
治理能力集中化：鉴权、超时控制、限流策略、操作审计等安全机制全部下沉到 MCP 中间层，实现了对下游服务端的统一管控，符合微服务架构下的安全规范。
支撑前端自动化：借助 MCP 工具的自省能力，大模型可以读取工具 Schema，进而自动生成前端页面或调用链，极大提升了开发效率。

这种设计思路对于正在构建 AI 原生应用或智能体的团队来说，是一个值得参考的实践方向。具体的模块规划可以参考：langchain4j-spring-ai-swagger-mcp/swagger-mcp-skills-plan.md。

模块架构与启动机制

整个解决方案以一个独立的 Spring Boot 服务形式存在，核心入口为 langchain4j-spring-ai-swagger-mcp/src/main/java/com/soft/nda/swagger/SwaggerMcpServerApplication.java。该服务对外暴露 MCP Server 能力，支持 SSE（Server-Sent Events）和 stdio 两种通信模式，默认采用 SSE 模式以适配远程调用场景。

在配置层面，开发者可以通过 Spring 配置文件灵活调整服务参数，以下是一个典型的配置示例（源自 application.yml）：

server:
port: 3000
transport:
mode: sse
swagger:
mcp:
services:
- serviceKey: local
openapiUrl: http://127.0.0.1:9010/v3/api-docs/default
baseUrl: http://127.0.0.1:9010
toolMode: perOperation
timeoutMs: 8000
maxBodyBytes: 1048576
auth:
type: none

实践建议：在微服务架构中，建议将 Swagger MCP 服务作为独立的中间件部署，与业务服务解耦，这样既能保证 MCP 服务的稳定性，又不会影响核心业务链路的性能。

核心组件深度解析

该框架的设计精髓在于将 OpenAPI 到 MCP Tool 的转换过程拆分为多个职责单一的组件，每个组件都专注于解决特定问题，这种模块化设计非常契合后端架构的演进需求。

3.1 OpenApiLoader：文档加载与缓存

该组件（langchain4j-spring-ai-swagger-mcp/src/main/java/com/soft/nda/swagger/openapi/OpenApiLoader.java）负责从 URL 或本地文件系统加载 OpenAPI 文档。它不仅会将文档解析为 OpenAPI 实例，还会缓存原始的 JSON Map 以便快速访问。对于需要鉴权才能访问的文档，它还支持配置自定义 Headers，确保在私有化部署环境中也能顺利拉取文档。

3.2 OpenApiNormalizer：接口结构规整

由于不同团队的 OpenAPI 文档编写风格各异，直接解析往往会导致结构不一致。OpenApiNormalizer（langchain4j-spring-ai-swagger-mcp/src/main/java/com/soft/nda/swagger/openapi/OpenApiNormalizer.java）的作用就是将这些异构的文档统一规整为标准化格式。它会自动补齐缺失的 operationId 字段，并提取出参数、requestBody、response schema 等关键元数据，为后续的工具生成奠定坚实基础。

3.3 ToolSpecFactory：工具规范生成

ToolSpecFactory（langchain4j-spring-ai-swagger-mcp/src/main/java/com/soft/nda/swagger/openapi/ToolSpecFactory.java）负责生成 MCP 工具的定义规范。它会根据规整后的 operation 信息生成工具名称（格式为 svc.{serviceKey}.{operationId}），并将参数和请求体映射为符合 MCP 协议的 input schema。这一步相当于为每个 API 接口创建了一份“使用说明书”，让大模型能够准确理解如何调用。

3.4 OpenApiInvoker：HTTP 请求执行器

当大模型决定调用某个工具时，OpenApiInvoker（langchain4j-spring-ai-swagger-mcp/src/main/java/com/soft/nda/swagger/openapi/OpenApiInvoker.java）会接收 operationId 和参数列表，拼装出真实的 HTTP 请求并发送到目标服务端。它支持 body 参数和 header 注入，并内置了超时控制和最大响应体限制，防止下游服务异常导致 MCP 服务资源耗尽。

3.5 SwaggerCallTool：MCP 工具统一入口

作为对外的门面，SwaggerCallTool（langchain4j-spring-ai-swagger-mcp/src/main/java/com/soft/nda/swagger/tools/SwaggerCallTool.java）暴露了多个核心工具，主要包括：

listApis：列出当前 MCP 服务下所有已加载的 OpenAPI 服务列表。
listOperations：分页返回指定服务的 operationId 列表，方便大模型浏览可用的操作。
call：通用调用入口，通过传入 serviceKey、operationId 和 args 参数即可发起任意 API 调用。
getComponents / getInfo / getServers / getPaths：提供自省能力，让大模型能够了解工具的参数结构。

✅ 设计亮点：通过将“列出服务”、“列出操作”和“执行调用”分离，使得 MCP 工具具备良好的可发现性和可操作性，大模型可以在运行时动态探索 API 能力。

MCP 服务配置与启动流程

Spring 配置入口位于 SwaggerMcpServerConfig，开发者可以根据实际部署环境选择 SSE 或 stdio 模式。该配置类会自动将上述核心组件注册到 MCP Server 中，并支持请求日志过滤，方便排查问题。

在 Windows CMD 环境下，典型的启动命令如下：

cd /d D:\workspace\langchain4j-spring-agent\langchain4j-spring-ai
mvn -pl langchain4j-spring-ai-swagger-mcp -am spring-boot:run

⚠️ 注意事项：在生产环境部署时，建议配置 JVM 内存参数和日志级别，并确保 MCP 服务与下游 API 服务之间的网络策略正确配置，避免因防火墙导致调用超时。

[AFFILIATE_SLOT_1]

完整调用闭环：SSE 模式实战演练

理解了组件构成后，我们通过 SSE 模式走一遍完整的调用流程。完整流程细节可参考：langchain4j-spring-ai-swagger-mcp/doc/swagger-mcp-call.md。

5.1 建立 SSE 会话

首先，客户端需要发起 SSE 连接以获取会话端点：

curl.exe -N "http://127.0.0.1:3000/sse"

拿到返回的 sessionId 后，将其拼接为 message endpoint，用于后续的消息交互。

5.2 列出可用工具

通过 tools/list 方法，大模型可以获取当前 MCP Server 上所有可用的工具列表：

curl.exe -X POST "http://127.0.0.1:3000/mcp/message?sessionId=你的sessionId" ^
  -H "Content-Type: application/json" ^
  -d "{\"jsonrpc\":\"2.0\",\"id\":\"1\",\"method\":\"tools/list\",\"params\":{}}"

5.3 获取 operationId 列表

在调用具体接口前，需要先查询某个服务下的操作列表：

curl.exe -X POST "http://127.0.0.1:3000/mcp/message?sessionId=你的sessionId" ^
  -H "Content-Type: application/json" ^
  -d "{\"jsonrpc\":\"2.0\",\"id\":\"2\",\"method\":\"tools/call\",\"params\":{\"name\":\"listOperations\",\"arguments\":{\"serviceKey\":\"local\"}}}"

5.4 发起通用调用

最后，通过 tools/call 方法传入 serviceKey、operationId 和参数，即可触发真实的下游 API 调用：

curl.exe -X POST "http://127.0.0.1:3000/mcp/message?sessionId=你的sessionId" ^
  -H "Content-Type: application/json" ^
  -d "{\"jsonrpc\":\"2.0\",\"id\":\"3\",\"method\":\"tools/call\",\"params\":{\"name\":\"call\",\"arguments\":{\"serviceKey\":\"local\",\"operationId\":\"getUserById\",\"args\":{\"id\":\"123\"}}}}"

效率提升：借助这套闭环，大模型可以在毫秒级完成从“理解接口”到“调用接口”的全过程，不再需要人工编写复杂的 HTTP 客户端代码。

设计要点与可扩展性探讨

为了让 Swagger MCP 更好地融入现有的后端架构，以下几个设计要点值得关注：

工具模式切换：支持 perOperation（默认）和 callOnly 两种模式，开发者可以根据大模型的能力选择更合适的工具组织方式。
鉴权集中化：对于需要认证的 API，可以在 MCP 层统一注入 bearer token、apiKey 或 basic auth 凭证，避免下游服务重复实现鉴权逻辑，提升安全性。
安全边界控制：可以对 OpenAPI 文档的拉取和下游 API 的调用进行 IP 白名单、调用频次等限制，防止恶意调用。
缓存与热更新：当 OpenAPI 文档更新时，可以通过 reload 强制刷新缓存，无需重启服务即可加载最新接口定义。

[AFFILIATE_SLOT_2]

常见问题与排障思路

在实际落地过程中，开发者可能会遇到以下问题，这里提供一些排查方向：

tools/list 为空：首先确认 MCP 服务是否已正常启动，以及客户端连接的服务端口是否正确。
listOperations 为空：通常是 OpenAPI 文档解析失败或文档地址不可达，检查网络连通性和文档格式。
call 报 operation not found：说明传入的 operationId 不存在，确认是否已加载对应的 OpenAPI 服务。

更多排错细节可以参考：langchain4j-spring-ai-swagger-mcp/doc/swagger-mcp-call.md。

小结与展望

Swagger MCP 的核心思路可以概括为一句话：把 OpenAPI 翻译成 LLM 能稳定执行的 MCP 工具。它有效解决了大模型无法稳定调用接口的痛点，并将鉴权、限流、日志等治理能力集中到中间层，是 AI Agent 生产环境接入的可靠选择。如果你正在探索“模型 + 业务系统”的落地路径，建议优先将接口能力工具化，再逐步完善提示词工程与前端自动化。

langchain4j-spring-ai-swagger-mcp

发表于 2026-08-07 16:06 jzssuanfa 阅读(22) 评论(0) 收藏举报

刷新页面返回顶部