swagger全集通+mock(prism)

一、Prism 在 Swagger 生态里的角色 先把关系讲清楚： swagger-editor：写 OpenAPI（yaml） swagger-ui：看文档 + 简易 Try-it（弱 mock） swagger-generator：代码→文档 swagger-codegen：文档→代码 Prism Mock：独立高性能 Mock Server + 契约校验

docker pull swaggerapi/swagger-editor docker pull swaggerapi/swagger-ui:latest docker pull swaggerapi/swagger-generator docker pull swaggerapi/swagger-codegen-cli-v3

• 四者都是 Swagger 生态，围绕 OpenAPI 规范工作
• Generator 和 Codegen 是反向工具：代码↔文档
• Editor 是手动写文档，UI 是展示文档
• 日常开发最常用：swagger-ui + swagger-generator（Spring Boot 标配）

Mock 在 Swagger 生态里的角色 + 用法（超清晰）

我直接用最简单、最贴近开发的方式给你讲，不绕弯子。

一句话定位

Mock = 假接口 / 模拟数据它的角色：在接口还没开发完时，先给前端返回假数据，让前端不用等后端，直接开发页面。

Mock 和你刚才问的 4 个工具是什么关系？

plaintext

swagger-editor → 写接口文档 swagger-generator → 代码生成文档 swagger-ui → 看文档 + 调接口 swagger-codegen → 文档生成代码 ↓ 【Mock】 专门负责：**给前端返回假数据**

Mock 是 Swagger/OpenAPI 生态的 “增强能力”，不是一个独立工具，但处处能用。

一、Mock 到底在哪里使用？（3 个最常用位置）

1. swagger-ui 里自带 Mock（最常用）

你在 Swagger 页面点Try it out → Execute如果后端没启动、没写好，UI 可以直接返回假数据。

这就是Mock。

2. swagger-editor 里写 Mock 示例值

你写 OpenAPI 文档时，可以写：

yaml

example: "张三"

yaml

schema: type: string example: "13800138000"

这些example 就是 Mock 数据。

Editor 会预览，UI 会展示，Mock 服务会用它返回假数据。

3. 独立 Mock 服务（前端最爱）

比如：

• swagger-mock
• mockoon
• easy-mock
• yapi
• springcloud 自带 mock

它们读取你的 OpenAPI 文档，自动启动一个假接口服务：

plaintext

前端请求 → Mock 服务 → 直接返回假数据

后端还没开发完，前端就能正常调用、调试页面。

二、最清晰的角色总结

Mock = 临时后端

在整个流程里的位置：

1. 用swagger-editor写接口文档 + 写 mock 示例值
2. 用swagger-ui查看 mock 格式
3. 用mock 服务生成假接口给前端使用
4. 等后端写完，再把 mock 换成真实接口

三、最简单理解（开发必懂）

• Swagger 负责：定义接口长什么样
• Mock 负责：接口还没好时，先顶替它干活

前端永远不用等后端！

四、你最关心的：开发中怎么用？（真实流程）

1. 前后端先约定接口文档（Swagger）
2. Mock 服务根据文档自动生成假接口
3. 前端调用假接口开发页面
4. 后端同时写真实接口
5. 后端完成后，前端切换域名 → 上线

这就是前后端分离最标准的工作流

终极极简总结

• Swagger：定义接口
• Mock：提供假接口
• Mock 是 Swagger 的 “临时替身”
• 在哪里用？Swagger-UI / 编辑器 / 独立 Mock 服务

Prism（Stoplight Prism）就是一个专门跑在 OpenAPI/Swagger 文档上的 “专业 Mock Server + 契约验证器”，在你前面问的 Swagger 工具链里，它是独立的、最强的 Mock 服务，用来替代零散的小 mock 工具。

一、Prism 在 Swagger 生态里的角色

先把关系讲清楚：

• swagger-editor：写 OpenAPI（yaml）
• swagger-ui：看文档 + 简易 Try-it（弱 mock）
• swagger-generator：代码→文档
• swagger-codegen：文档→代码
• Prism Mock：独立高性能 Mock Server + 契约校验

一句话：

Swagger 负责定义接口，Prism 负责把这个定义变成一个 “真的能跑的假后端”。

它不是替代 swagger-ui，而是互补：

• UI：给人看、手动调
• Prism：给程序调、前端开发 / 自动化测试用

二、核心能力（为什么用 Prism 而不是自己写 mock）

1. 直接读 OpenAPI v2/v3（Swagger）不需要额外写 mock 规则，文档即 mock 配置。

2. 自动生成 mock 数据（两种模式）

   • 静态（static）：优先用你写的example
   • 动态（dynamic）：按 schema 随机生成 “像真的一样” 的数据（名字、电话、金额等）

3. 强请求校验（契约测试）前端传参不对（类型错、必填漏了），直接返回 400 并告诉你哪里错，不是随便返回假数据。

4. 支持代理（proxy）后端好了一半时：

   • 匹配的接口走真实后端
   • 没实现的接口继续 mock 平滑过渡。

5. 命令行启动，无侵入不用改前端、不用改后端，独立进程跑在 4010 端口。

三、在哪里使用（真实开发流程）

场景 1：前后端并行开发（最常用）

1. 架构师 / 后端用swagger-editor写出openapi.yaml
2. 启动 Prism：

   bash

   运行

   npm install -g @stoplight/prism-cli prism mock openapi.yaml --port 4010

3. 前端把 baseURL 改成http://localhost:4010
4. 直接开发页面，后端还没写一行代码
5. 后端写完后，前端切回真实地址即可

场景 2：接口文档 + Mock 一体化

• 文档里写好example
• Prism 自动用这些 example 返回数据
• swagger-ui 展示同样的 example
• 文档、UI、Mock 数据完全一致

场景 3：自动化测试（契约测试）

CI 环境启动 Prism，前端测试用例跑在 Prism 上：

• 接口变了 → Prism 校验失败 → 测试不通过
• 保证前端和文档永远对齐

四、和 swagger-ui 自带 mock 的区别

表格

结论：

• 开发 / 调试用 swagger-ui
• 前端开发 / 自动化测试 / 契约测试用 Prism

五、最简上手（复制就能用）

1. 安装

bash

运行

npm install -g @stoplight/prism-cli

2. 启动（静态，用文档里的 example）

bash

运行

prism mock openapi.yaml

访问：http://localhost:4010

3. 动态随机数据（推荐）

bash

运行

prism mock -d openapi.yaml

4. 代理模式（一半 mock，一半真实）

bash

运行

prism proxy openapi.yaml http://localhost:8080

六、一句话总结

Prism = 基于 OpenAPI/Swagger 的专业 Mock Server + 契约验证器。 在工具链里，它是文档到前端开发之间的关键桥梁，让前端完全不依赖后端进度。

案例:

harbor.jettech.com/jettechtools/swagger-editor ：编写openapi.yaml
harbor.jettech.com/jettechtools/swaggerapi/swagger-ui ：展示openapi.yaml和轻量版本mock
swaggerapi/swagger-codegen-cli-v3 ：根据 openapi.yaml生成代码
harbor.jettech.com/jettechtools/swaggerapi/swagger-generator ：根据代码生成openapi文档


第一步：编辑器

docker run -it --net=host -d harbor.jettech.com/jettechtools/swagger-editor:latest

第二步骤:展示和轻量的mock

docker run -it --net=host -d harbor.jettech.com/jettechtools/swaggerapi/swagger-ui:latest

这里可以自动以mock

[root@localhost ai]# npm install -g @stoplight/prism-cli [root@localhost ai]# cat openapi3_2.yaml openapi: 3.0.0 info: title: Demo API version: 1.0.0 servers: - url: http://172.16.10.250:4010 paths: /users: get: summary: 获取用户列表 responses: '200': description: OK content: application/json: schema: type: array items: type: object properties: id: type: integer name: type: string [root@localhost ai]# prism mock -d -h 0.0.0.0 -p 4010 openapi3_2.yaml

注意这个，这个是mock的地址：
servers:
- url: http://172.16.10.250:4010

prism mock -d -h 0.0.0.0 -p 4010 openapi3_2.yaml 这个就会基于 openapi3_2.yaml 接口契约是生成随机的数据接口

然后在ui层面：