stoplight/prism

Prism 镜像文档

概述

Prism 是一套用于 API 模拟和契约测试的工具包，支持 OpenAPI v2（原 Swagger）和 OpenAPI v3.x。它能从 API 规范文档生成逼真的模拟服务器，提供契约测试功能，并支持多种 API 规范格式，帮助开发者在 API 开发周期早期进行测试和验证。

核心功能和特性

• 模拟服务器（Mock Servers）：基于 API 规范文档生成可交互的模拟服务器，无需后端实现即可展示 API 工作方式。
• 验证代理（Validation Proxy）：作为代理服务器检查 API 实现与规范文档的一致性，支持契约测试。
• 全面的 API 规范支持：兼容 OpenAPI v3.1、v3.0、v2.0（原 Swagger）及 Postman Collections。

使用场景和适用范围

• API 设计阶段：在后端开发前，为团队成员和外部消费者提供可测试的 API 模拟服务。
• 前端并行开发：前端开发者可基于模拟服务器进行开发，无需等待后端接口就绪。
• 契约测试：验证 API 实现是否符合规范定义，确保前后端协作一致性。
• CI/CD 集成：作为独立工具集成到持续集成流程，自动验证 API 变更的合规性。

Docker 使用方法

拉取镜像

bash
docker pull stoplight/prism

运行模拟服务器

使用本地 OpenAPI 规范文件启动模拟服务器：

bash
# 挂载当前目录并映射端口，启动模拟服务器
docker run --rm -v $(pwd):/app -p 4010:4010 stoplight/prism mock /app/openapi.yaml

参数说明：

• -v $(pwd):/app：将本地当前目录挂载到容器内 /app 目录，使容器可访问规范文件
• -p 4010:4010：映射容器 4010 端口到主机，默认模拟服务器监听 4010 端口
• mock /app/openapi.yaml：指定模拟模式及容器内规范文件路径

启动后可通过 http://localhost:4010 访问模拟服务器，具体端点可查看启动日志中的 URL 列表。

运行验证代理

将请求代理到实际 API 服务器并验证合规性：

bash
# 启动验证代理，转发请求到目标服务器并验证
docker run --rm -v $(pwd):/app -p 4010:4010 stoplight/prism proxy /app/openapi.yaml https://api.example.com

参数说明：

• proxy：指定代理模式，后接规范文件路径和目标 API 服务器 URL
• 所有发送到 http://localhost:4010 的请求将被转发至 https://api.example.com，并根据规范验证请求合法性

高级配置

常见问题

Docker 中无法访问模拟服务器？

Prism 默认监听 localhost（127.0.0.1），Docker 环境下需指定 -h 0.0.0.0 允许外部访问：

bash
docker run --rm -v $(pwd):/app -p 4010:4010 stoplight/prism mock -h 0.0.0.0 /app/spec.yaml

包含 basePath 时返回 404？

OpenAPI v2.0 的 basePath 已合并到 v3.0 的 server.url。Prism 将 OAS2 的 host + basePath 视为完整基础 URL，请求无需重复包含 basePath。例如规范中 basePath: /api/v1 且路径定义为 /users，直接请求 http://localhost:4010/users 即可，无需添加 /api/v1 前缀。

路线图

• 内容协商支持
• 安全验证功能
• 验证代理模式
• 录制/学习模式（从 HTTP 流量自动生成 OpenAPI 规范）
• 数据持久化（支持模拟服务器状态保持）

文档和社区

• 官方文档
• https://github.com/stoplightio/prism/discussions