swagger全集通+mock(prism)

一、Prism 在 Swagger 生态里的角色 先把关系讲清楚 swagger-editor写 OpenAPIyaml 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-v3OpenAPI 文档 → 代码生成客户端 / 服务端代码全端开发❌ 用现成文档生成四者都是 Swagger 生态围绕 OpenAPI 规范工作Generator 和 Codegen 是反向工具代码↔文档Editor 是手动写文档UI 是展示文档日常开发最常用swagger-ui swagger-generatorSpring Boot 标配Mock 在 Swagger 生态里的角色 用法超清晰我直接用最简单、最贴近开发的方式给你讲不绕弯子。一句话定位Mock 假接口 / 模拟数据它的角色在接口还没开发完时先给前端返回假数据让前端不用等后端直接开发页面。Mock 和你刚才问的 4 个工具是什么关系plaintextswagger-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 文档时可以写yamlexample: 张三yamlschema: type: string example: 13800138000这些example 就是 Mock 数据。Editor 会预览UI 会展示Mock 服务会用它返回假数据。3. 独立 Mock 服务前端最爱比如swagger-mockmockooneasy-mockyapispringcloud 自带 mock它们读取你的 OpenAPI 文档自动启动一个假接口服务plaintext前端请求 → Mock 服务 → 直接返回假数据后端还没开发完前端就能正常调用、调试页面。二、最清晰的角色总结Mock 临时后端在整个流程里的位置用swagger-editor写接口文档 写 mock 示例值用swagger-ui查看 mock 格式用mock 服务生成假接口给前端使用等后端写完再把 mock 换成真实接口三、最简单理解开发必懂Swagger 负责定义接口长什么样Mock 负责接口还没好时先顶替它干活前端永远不用等后端四、你最关心的开发中怎么用真实流程前后端先约定接口文档SwaggerMock 服务根据文档自动生成假接口前端调用假接口开发页面后端同时写真实接口后端完成后前端切换域名 → 上线这就是前后端分离最标准的工作流终极极简总结Swagger定义接口Mock提供假接口Mock 是 Swagger 的 “临时替身”在哪里用Swagger-UI / 编辑器 / 独立 Mock 服务PrismStoplight Prism就是一个专门跑在 OpenAPI/Swagger 文档上的 “专业 Mock Server 契约验证器”在你前面问的 Swagger 工具链里它是独立的、最强的 Mock 服务用来替代零散的小 mock 工具。一、Prism 在 Swagger 生态里的角色先把关系讲清楚swagger-editor写 OpenAPIyamlswagger-ui看文档 简易 Try-it弱 mockswagger-generator代码→文档swagger-codegen文档→代码Prism Mock独立高性能 Mock Server 契约校验一句话Swagger 负责定义接口Prism 负责把这个定义变成一个 “真的能跑的假后端”。它不是替代 swagger-ui而是互补UI给人看、手动调Prism给程序调、前端开发 / 自动化测试用二、核心能力为什么用 Prism 而不是自己写 mock直接读 OpenAPI v2/v3Swagger不需要额外写 mock 规则文档即 mock 配置。自动生成 mock 数据两种模式静态static优先用你写的example动态dynamic按 schema 随机生成 “像真的一样” 的数据名字、电话、金额等强请求校验契约测试前端传参不对类型错、必填漏了直接返回 400 并告诉你哪里错不是随便返回假数据。支持代理proxy后端好了一半时匹配的接口走真实后端没实现的接口继续 mock 平滑过渡。命令行启动无侵入不用改前端、不用改后端独立进程跑在 4010 端口。三、在哪里使用真实开发流程场景 1前后端并行开发最常用架构师 / 后端用swagger-editor写出openapi.yaml启动 Prismbash运行npm install -g stoplight/prism-cli prism mock openapi.yaml --port 4010前端把 baseURL 改成http://localhost:4010直接开发页面后端还没写一行代码后端写完后前端切回真实地址即可场景 2接口文档 Mock 一体化文档里写好examplePrism 自动用这些 example 返回数据swagger-ui 展示同样的 example文档、UI、Mock 数据完全一致场景 3自动化测试契约测试CI 环境启动 Prism前端测试用例跑在 Prism 上接口变了 → Prism 校验失败 → 测试不通过保证前端和文档永远对齐四、和 swagger-ui 自带 mock 的区别表格能力swagger-ui Try-itPrism Mock启动方式内嵌网页依赖后端独立命令行服务数据生成简单默认值静态 example 动态 Faker请求校验弱强校验类型 / 必填 / 格式并发请求不适合适合前端 / 自动化测试代理过渡无有多环境本地后端本地 / 测试 / CI 都可部署结论开发 / 调试用 swagger-ui前端开发 / 自动化测试 / 契约测试用 Prism五、最简上手复制就能用1. 安装bash运行npm install -g stoplight/prism-cli2. 启动静态用文档里的 examplebash运行prism mock openapi.yaml访问http://localhost:40103. 动态随机数据推荐bash运行prism mock -d openapi.yaml4. 代理模式一半 mock一半真实bash运行prism proxy openapi.yaml http://localhost:8080六、一句话总结Prism 基于 OpenAPI/Swagger 的专业 Mock Server 契约验证器。 在工具链里它是文档到前端开发之间的关键桥梁让前端完全不依赖后端进度。案例:harbor.jettech.com/jettechtools/swagger-editor 编写openapi.yamlharbor.jettech.com/jettechtools/swaggerapi/swagger-ui 展示openapi.yaml和轻量版本mockswaggerapi/swagger-codegen-cli-v3 根据 openapi.yaml生成代码harbor.jettech.com/jettechtools/swaggerapi/swagger-generator 根据代码生成openapi文档第一步编辑器docker run -it --nethost -d harbor.jettech.com/jettechtools/swagger-editor:latest第二步骤:展示和轻量的mockdocker run -it --nethost -d harbor.jettech.com/jettechtools/swaggerapi/swagger-ui:latest这里可以自动以mock[rootlocalhost ai]# npm install -g stoplight/prism-cli [rootlocalhost 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 [rootlocalhost ai]# prism mock -d -h 0.0.0.0 -p 4010 openapi3_2.yaml注意这个这个是mock的地址servers:- url: http://172.16.10.250:4010prism mock -d -h 0.0.0.0 -p 4010 openapi3_2.yaml 这个就会基于 openapi3_2.yaml 接口契约是生成随机的数据接口然后在ui层面