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-editor	编写 / 编辑 OpenAPI 文档	手动写文档	架构师 / 后端	✅ 需要手动写
swagger-ui	展示文档 + 在线调试	展示文档	前端 / 测试 / 开发	❌ 不需要
swagger-generator	代码 → OpenAPI 文档	自动生成文档	后端开发	❌ 代码注解生成
swagger-codegen-cli-v3	OpenAPI 文档 → 代码	生成客户端 / 服务端代码	全端开发	❌ 用现成文档生成

四者都是 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 = 临时后端

在整个流程里的位置：

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

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

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

前端永远不用等后端！

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

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

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

终极极简总结

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）

直接读 OpenAPI v2/v3（Swagger） 不需要额外写 mock 规则，文档即 mock 配置。
自动生成 mock 数据（两种模式）
- 静态（static） ：优先用你写的 example
- 动态（dynamic）：按 schema 随机生成 "像真的一样" 的数据（名字、电话、金额等）
强请求校验（契约测试） 前端传参不对（类型错、必填漏了），直接返回 400 并告诉你哪里错，不是随便返回假数据。
支持代理（proxy） 后端好了一半时：
- 匹配的接口走真实后端
- 没实现的接口继续 mock 平滑过渡。
命令行启动，无侵入 不用改前端、不用改后端，独立进程跑在 4010 端口。

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

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

架构师 / 后端用 swagger-editor 写出 openapi.yaml

启动 Prism： bash

运行

复制代码

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

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

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

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

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

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

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

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

表格

能力	swagger-ui Try-it	Prism Mock
启动方式	内嵌网页，依赖后端	独立命令行服务
数据生成	简单默认值	静态 example + 动态 Faker
请求校验	弱	强校验（类型 / 必填 / 格式）
并发请求	不适合	适合前端 / 自动化测试
代理过渡	无	有
多环境	本地后端	本地 / 测试 / CI 都可部署

结论：

开发 / 调试用 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层面：