1. 项目概述当AI成为你的API设计搭档最近在重构一个老项目的后端服务面对几十个混乱不堪、文档缺失的接口我和团队都感到头疼。手动编写Swagger/OpenAPI文档、再搭建Mock服务器来供前端联调这套流程不仅耗时而且一旦需求变更维护文档和Mock数据就成了新的负担。就在我们纠结于工具选型时我尝试了将AI引入到API设计工作流中效果出乎意料。这个项目我称之为“MonkeyCode”核心就是利用AI大语言模型如GPT-4、Claude 3或国内的同级别模型将自然语言描述的需求直接转化为结构严谨的RESTful API接口定义并一键生成可运行的Mock服务。它解决的痛点很明确让API设计阶段从“写文档”变成“提需求”让Mock服务从“手动维护”变成“自动同步”。简单来说MonkeyCode是一个工作流和一系列脚本工具的集合它不依赖于某个特定的AI平台而是将AI作为核心的“翻译官”和“生成器”。你只需要用口语化的方式描述你想要什么接口比如“需要一个用户登录接口接收手机号和密码成功返回token和用户基本信息失败返回错误码”AI就能帮你生成标准的OpenAPI 3.0规范YAML/JSON格式紧接着工具链会基于这份规范自动启动一个Mock服务器前端同学立刻就能拿到真实的URL进行调用和测试。整个过程从想法到可测试的Mock端点可能只需要几分钟。这适合谁呢我认为它非常适合中小型敏捷团队的全栈工程师、后端开发负责人以及独立开发者。尤其是当你在项目初期进行技术方案评审、快速原型验证或者面对大量重复性接口定义工作时MonkeyCode能极大提升效率确保API设计的一致性并让前后端协作的“等待时间”几乎降为零。接下来我将详细拆解这套工作流的核心思路、具体实现以及我趟过的那些坑。2. 核心思路与方案选型为什么是“AI OpenAPI Mock”这个组合在构思MonkeyCode时我评估过几种常见的API设计协作模式。传统上我们可能会用Swagger Editor手动编写YAML或者用Postman的Collection。但这些方式本质上还是“手写”只不过从代码变成了另一种格式的代码。另一种思路是使用像Apifox、Apidog这类一体化协作平台它们功能强大但往往有较强的平台绑定属性且自定义和自动化程度有时不能满足极客需求。我选择“AI OpenAPI Mock”这个技术栈是基于以下几个核心考量2.1 为什么选择OpenAPI规范作为中间枢纽OpenAPI SpecificationOAS是目前RESTful API描述事实上的标准。它有几个不可替代的优势标准化与工具生态丰富OAS是一个机器可读的规范围绕它有海量的工具包括代码生成器Swagger Codegen, OpenAPI Generator、文档生成器Swagger UI, ReDoc、Mock服务器Prism, Stoplight Studio以及校验工具。选择OAS就意味着你接入了整个生态。单一数据源API的设计信息路径、参数、响应体结构被定义在一个文件中。无论是生成文档、Mock数据还是最终的服务端/客户端代码都源于此保证了信息的一致性避免了“文档是文档代码是代码”的割裂问题。人机皆可读YAML格式对开发者相对友好便于人工审查和版本控制如Git。在MonkeyCode中OAS文件是整个流程的“中枢神经”。AI的任务就是生成它后续所有步骤都依赖于它。2.2 为什么用AI来生成OAS而不是手写这源于对开发体验的优化。手写OAS尤其是复杂的嵌套对象和响应示例非常繁琐且容易出错。AI特别是经过代码和自然语言混合训练的大模型在这方面有天然优势理解意图它能将模糊的自然语言需求转化为精确的技术规范。你说“分页列表”它能理解并生成包含page,size,total,items等标准字段的Schema。知识库与最佳实践优秀的模型内化了大量的API设计最佳实践如HTTP状态码的使用、命名规范、数据格式。你可以要求它“遵循RESTful风格”、“使用JSON:API规范”或“采用公司内部的错误码规范”它通常能很好地执行。生成示例数据为每个字段生成合理的Mock值这对于Mock服务至关重要。AI可以根据字段名和类型如username: string生成像“john_doe”这样的示例比单纯的“string”有用得多。2.3 Mock服务器的选择轻量、实时、与OAS无缝集成有了OAS文件我们需要一个能“读懂”它并提供模拟响应的服务器。我选择了Prism由Stoplight团队开发。原因如下专注MockPrism是专业的OAS Mock服务器不像一些全功能平台那样沉重。动态响应它可以根据请求参数和OAS中定义的示例example或Schema动态生成符合规范的响应数据。如果OAS里没有示例它会基于Schema如type: string,format: email生成一个合理的值如“userexample.com”。CLI友好易于自动化Prism可以通过命令行一键启动完美契合我们的自动化脚本流程。支持请求验证它能在Mock的同时验证 incoming request 是否符合OAS定义对于调试很有帮助。注意市面上类似工具还有Mockoon、API Sprout等。选择Prism主要是看中其与OAS标准的贴合度以及动态生成能力。如果你的场景需要更复杂的逻辑响应如根据请求ID返回特定数据可能需要自行封装或选择其他支持自定义响应脚本的工具。综合来看MonkeyCode的架构流水线非常清晰用户输入自然语言需求 - AI引擎生成/补全OAS规范文件 - 工具链读取OAS文件并启动Prism Mock服务器。这个链条中的每个环节都可以替换比如换用不同的AI服务、不同的Mock工具但核心思想不变用AI降低设计门槛用标准规范保证输出质量用自动化工具提升交付速度。3. 环境准备与工具链搭建要让MonkeyCode跑起来你需要准备好几个关键组件。我会以MacOS/Linux环境为例Windows用户可以通过WSL或相应的包管理器获得类似体验。3.1 核心依赖安装首先是Mock服务器Prism的安装。它基于Node.js所以确保你的系统已经安装了Node.js版本14或以上和npm。# 使用npm全局安装Prism npm install -g stoplight/prism-cli # 安装完成后验证安装 prism --version接下来是AI交互的核心。这里有两种主流方式方式一使用OpenAI API或兼容API如Azure OpenAI。这是最直接的方式你需要一个API Key。# 无需安装额外CLI我们将通过编写Python/Node.js脚本调用。 # 以Python为例安装openai库 pip install openai方式二使用本地大模型。如果你注重隐私、成本或网络环境可以部署本地模型。使用ollama是一个极简的选择它能方便地拉取和运行各种开源模型。# 安装ollama请参考官网 https://ollama.com/ 的安装指南 # 拉取一个适合代码生成的模型例如 deepseek-coder 或 qwen2.5-coder ollama pull deepseek-coder:6.7b # 运行模型服务 ollama run deepseek-coder:6.7b # ollama默认会在11434端口提供类OpenAI的API接口非常方便。3.2 项目结构与初始化创建一个项目目录结构如下monkeycode-project/ ├── api-specs/ # 存放生成的OpenAPI规范文件 │ └── petstore.yaml # 示例 ├── scripts/ # 存放自动化脚本 │ ├── generate_spec.py # AI生成OAS的脚本 │ └── start_mock.sh # 启动Mock服务的脚本 ├── .env # 存储API Key等敏感信息记得加入.gitignore └── README.md初始化一个Python虚拟环境是个好习惯cd monkeycode-project python3 -m venv venv source venv/bin/activate # Linux/Mac # venv\Scripts\activate # Windows pip install openai python-dotenv requests在.env文件中配置你的AI服务密钥OPENAI_API_KEYsk-your-secret-key-here # 如果使用本地ollama则配置其base_url # OPENAI_API_BASEhttp://localhost:11434/v1 # OPENAI_API_KEYnot-needed # ollama可能不需要key但某些客户端要求非空3.3 第一个OpenAPI规范模板为了让AI更好地生成内容我们最好提供一个基础模板。这个模板定义了OpenAPI的版本、基础信息以及一些通用的组件如标准错误响应Schema。这能引导AI在正确的框架下填充内容。创建一个api-specs/template.yaml文件openapi: 3.0.3 info: title: MonkeyCode Generated API version: 1.0.0 description: API automatically generated by MonkeyCode with AI. servers: - url: http://localhost:4010 # Prism默认Mock端口 description: Mock server paths: {} # 路径将由AI填充 components: schemas: ErrorResponse: type: object properties: code: type: integer description: 业务错误码 message: type: string description: 错误信息 requestId: type: string description: 请求ID用于追踪 required: - code - message securitySchemes: BearerAuth: type: http scheme: bearer这个模板预先定义了通用的错误响应格式和一个Bearer Token的安全方案AI在生成具体接口时可以直接引用#/components/schemas/ErrorResponse保证所有接口的错误格式统一。4. 核心脚本解析如何让AI理解并生成OAS这是MonkeyCode的“大脑”部分。我们需要编写一个脚本其核心功能是接收用户的需求描述结合基础模板调用AI服务生成或更新一个完整的OpenAPI规范文件。4.1 构建高效的AI提示词Prompt与AI沟通的质量直接决定了输出结果的质量。经过多次试验我总结出一个高效的Prompt结构你是一个专业的API架构师精通OpenAPI 3.0.3规范。请根据以下用户需求生成或补充OpenAPI规范。 【现有规范基础】 {existing_spec_yaml} 【用户需求】 {user_requirement} 【任务要求】 1. 严格遵循RESTful设计原则。 2. 使用JSON作为请求和响应的数据格式。 3. 为每个操作operation提供清晰的summary和description。 4. 为每个请求参数和响应字段提供详细的description。 5. 为每个HTTP状态码至少200成功和4xx/5xx错误提供响应示例example。示例数据应尽可能真实、合理。 6. 合理利用components部分对可复用的Schema如分页结构、用户对象进行定义和引用。 7. 如果需求中涉及身份验证请使用Bearer Token方式securitySchemes中已定义。 请直接输出完整的、可执行的OpenAPI YAML内容不要包含任何解释性文字。这个Prompt做了几件关键事角色设定让AI进入“专家”状态。提供上下文传入现有的规范基础可能是模板也可能是已存在的部分API让AI在此基础上进行增量生成或修改而不是每次都从零开始。明确要求列出了具体、可检查的条目如提供示例、使用components极大地提高了输出的规范性和可用性。格式化指令要求直接输出YAML方便脚本直接捕获。4.2 Python脚本实现generate_spec.py下面是一个使用OpenAI API的脚本示例。如果你使用本地ollama只需将base_url修改为http://localhost:11434/v1并选择对应的模型名如deepseek-coder。import openai import yaml import os from dotenv import load_dotenv import sys # 加载环境变量 load_dotenv() # 配置OpenAI客户端 client openai.OpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_API_BASE, https://api.openai.com/v1) # 默认OpenAI可覆盖为ollama地址 ) def read_yaml_file(filepath): 读取YAML文件内容 try: with open(filepath, r, encodingutf-8) as f: return yaml.safe_load(f) except FileNotFoundError: print(f文件 {filepath} 不存在将使用空基础。) return None def write_yaml_file(filepath, data): 将数据写入YAML文件 with open(filepath, w, encodingutf-8) as f: yaml.dump(data, f, allow_unicodeTrue, sort_keysFalse, default_flow_styleFalse) print(f规范已成功写入: {filepath}) def generate_openapi_spec(user_requirement, base_spec_path, output_spec_path): 核心生成函数 :param user_requirement: 用户需求描述字符串 :param base_spec_path: 现有基础规范文件路径 :param output_spec_path: 输出文件路径 # 1. 读取现有规范 existing_spec read_yaml_file(base_spec_path) existing_spec_yaml yaml.dump(existing_spec, allow_unicodeTrue) if existing_spec else # 2. 构建Prompt prompt f你是一个专业的API架构师精通OpenAPI 3.0.3规范。请根据以下用户需求生成或补充OpenAPI规范。 【现有规范基础】 {existing_spec_yaml} 【用户需求】 {user_requirement} 【任务要求】 1. 严格遵循RESTful设计原则。 2. 使用JSON作为请求和响应的数据格式。 3. 为每个操作operation提供清晰的summary和description。 4. 为每个请求参数和响应字段提供详细的description。 5. 为每个HTTP状态码至少200成功和4xx/5xx错误提供响应示例example。示例数据应尽可能真实、合理。 6. 合理利用components部分对可复用的Schema如分页结构、用户对象进行定义和引用。 7. 如果需求中涉及身份验证请使用Bearer Token方式securitySchemes中已定义。 请直接输出完整的、可执行的OpenAPI YAML内容不要包含任何解释性文字。 # 3. 调用AI模型 try: response client.chat.completions.create( modelos.getenv(OPENAI_MODEL, gpt-4-turbo-preview), # 可配置本地模型如deepseek-coder messages[ {role: system, content: 你是一个输出纯净YAML的OpenAPI规范生成器。}, {role: user, content: prompt} ], temperature0.2, # 温度调低输出更稳定、确定性更高 streamFalse ) ai_output response.choices[0].message.content.strip() # 4. 清理输出AI有时会在YAML前后加yaml标记 if ai_output.startswith(yaml): ai_output ai_output[7:] if ai_output.endswith(): ai_output ai_output[:-3] ai_output ai_output.strip() # 5. 解析并保存YAML generated_spec yaml.safe_load(ai_output) write_yaml_file(output_spec_path, generated_spec) print(生成成功) except openai.APIError as e: print(f调用AI API时出错: {e}) sys.exit(1) except yaml.YAMLError as e: print(f解析AI返回的YAML时出错: {e}) print(AI返回的原始内容) print(ai_output) sys.exit(1) if __name__ __main__: # 示例通过命令行参数或直接赋值获取需求 if len(sys.argv) 1: requirement .join(sys.argv[1:]) else: # 也可以从文件读取或交互式输入 requirement input(请输入你的API需求描述: ) base_spec api-specs/template.yaml # 基础模板 output_spec api-specs/generated_api.yaml # 输出文件 generate_openapi_spec(requirement, base_spec, output_spec)4.3 脚本使用与迭代运行脚本非常简单cd scripts python generate_spec.py “管理一个简单的待办事项Todo系统。需要以下接口1. 创建待办事项POST /todos需要标题和可选描述。2. 获取待办事项列表GET /todos支持分页查询。3. 获取单个待办事项详情GET /todos/{id}。4. 更新待办事项状态PATCH /todos/{id}主要更新完成状态。5. 删除待办事项DELETE /todos/{id}。所有操作都需要Bearer Token认证。”脚本会调用AI生成一个完整的generated_api.yaml文件。你可以打开这个文件查看AI应该已经生成了完整的paths、components.schemas.Todo、components.schemas.TodoList包含分页并为每个接口的200、400、401、404、500等状态码提供了示例响应。实操心得第一次生成的结果可能不完美比如字段类型不对或者示例数据不合理。MonkeyCode的精髓在于“对话式迭代”。你不必手动修改YAML而是可以再次运行脚本将base_spec_path指向刚刚生成的generated_api.yaml然后在user_requirement中提出修改意见例如“在刚才生成的Todo API基础上为创建接口的请求体增加一个priority字段类型为整数枚举值为1低、2中、3高默认为2。同时在获取列表的响应中增加按priority和createdAt倒序排序的说明。” AI会理解现有结构并应用你的修改。5. 一键部署Mock服务与实时测试生成了标准的OpenAPI规范文件后启动Mock服务就变得异常简单。我们编写一个Shell脚本或批处理文件来封装这个命令。5.1 启动脚本start_mock.sh#!/bin/bash # scripts/start_mock.sh SPEC_FILE${1:-../api-specs/generated_api.yaml} # 默认使用生成的API文件 PORT${2:-4010} # 默认端口4010 echo 正在启动Mock服务器使用规范文件: $SPEC_FILE echo Mock服务地址: http://localhost:$PORT prism mock $SPEC_FILE --port $PORT给脚本执行权限并运行chmod x scripts/start_mock.sh cd scripts ./start_mock.sh或者直接指定文件./start_mock.sh ../api-specs/petstore.yaml 8080Prism启动后会在控制台输出可用的端点。它默认会使用OAS文件中servers的URL如果没有则使用http://localhost:[port]。5.2 测试生成的API打开浏览器或使用你喜欢的API测试工具如Postman, curl, httpie获取待办列表GET http://localhost:4010/todos?page1size10创建待办事项curl -X POST http://localhost:4010/todos \ -H Content-Type: application/json \ -H Authorization: Bearer fake-jwt-token-for-mock \ -d {title: 学习MonkeyCode, description: 完成这篇博文}Prism会根据OAS中定义的示例example或Schema返回一个结构正确、数据合理的响应。例如对于GET /todos/{id}如果OAS中定义了响应示例它会返回示例数据如果没有它会根据Schematype: string,format: uuid生成一个随机的UUID作为id。5.3 Mock服务的进阶配置Prism支持一些有用的参数可以整合进启动脚本--dynamic这是默认行为根据Schema生成动态数据。--cors启用CORS头方便前端直接调用。--errors模拟错误响应。例如--errors会随机返回4xx/5xx错误--errors 404,500则只模拟这两种错误。这在测试前端错误处理时非常有用。一个更健壮的启动脚本可能如下#!/bin/bash SPEC_FILE${1:-../api-specs/generated_api.yaml} PORT${2:-4010} DELAY${3:-0} # 模拟网络延迟单位毫秒 echo 启动Mock服务器 (延迟: ${DELAY}ms) prism mock $SPEC_FILE --port $PORT --cors --delay $DELAY6. 工程化与团队协作实践MonkeyCode在个人项目中很好用但要融入团队协作流程还需要一些工程化的考量。6.1 将OAS文件纳入版本控制生成的api-specs/generated_api.yaml应该被提交到Git仓库。这带来了几个好处设计可追溯每次API设计的变更都通过AI生成新的规范文件并提交Git历史记录了设计演进的过程。团队共享前后端开发人员都基于同一份权威的规范文件工作。作为合同这份文件就是前后端之间的“合同”Mock服务和后续的代码生成都基于此减少了沟通歧义。6.2 设计评审流程虽然AI能生成不错的初稿但人工评审必不可少。建议的流程是产品经理或后端开发者提出需求描述。运行MonkeyCode生成初版OAS文件。在Git仓库中发起一个Pull RequestPR将生成的OAS文件变更提交。后端、前端、测试同学在PR中评审这份API设计路径是否合理字段命名是否清晰状态码使用是否正确错误格式是否统一评审意见可以再次作为“用户需求”输入给AI进行迭代修改直到达成一致。合并PR更新主分支的OAS文件。6.3 与CI/CD管道集成你可以在CI持续集成管道中增加一个验证步骤例如语法校验使用swagger-cli或openapi-validator校验生成的OAS文件语法是否正确。风格检查使用spectral一个OpenAPI风格检查工具来强制执行团队的API设计规则如必须提供描述、必须使用ISO8601时间格式等。自动化Mock部署在测试环境中可以自动基于主分支的OAS文件启动一个Prism Mock服务供自动化测试或前端开发环境使用。一个简单的GitHub Actions工作流示例name: Validate OpenAPI Spec on: [pull_request] jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Validate OpenAPI Spec run: | npm install -g apideck/portman # 或者使用其他校验工具 # 对api-specs/目录下的yaml文件进行校验 npx portman --cliOptionsFile portman-config.json7. 常见问题、局限性与应对策略在实际使用MonkeyCode的过程中我遇到了一些典型问题以下是总结和解决方案。7.1 AI生成内容不稳定或不符合预期问题生成的字段类型错误如该用integer用了string示例数据荒谬或遗漏了某些需求点。解决优化Prompt这是最关键的一步。在Prompt中提供更具体的约束例如“所有时间字段必须使用string类型并设置format: date-time”。可以要求AI“先思考再输出”有时能提升逻辑性。提供更详细的上下文在“现有规范基础”中包含你们团队已经定义好的通用组件分页结构、标准响应头等AI会倾向于复用。分步生成不要试图用一个复杂的Prompt生成整个系统。先生成核心的components/schemas数据模型再基于这些模型去生成各个接口的paths。人工微调与迭代接受AI作为“高级助手”的定位。第一次生成完成度能达到70%-80%即可剩下的通过“对话式迭代”逐步修正。将修改需求描述清楚再次运行脚本。7.2 复杂业务逻辑难以描述问题某些接口逻辑复杂涉及条件判断、状态流转单纯用自然语言描述AI可能无法准确转化为API设计。解决拆分需求将复杂接口拆分成多个简单的、原子性的操作。例如“用户下单”可能拆成“创建订单”、“扣减库存”、“支付回调”等多个接口。使用伪代码或序列图辅助描述在需求描述中可以加入简单的伪代码或文字描述的序列图。例如“流程1. 客户端POST /orders。2. 系统验证库存调用内部服务。3. 若库存充足创建订单记录状态为‘待支付’并返回支付URL。4. 库存不足则返回错误。”先设计后生成对于核心复杂接口可以先在白板或设计工具上画出大致的请求响应结构然后将这个结构作为“现有规范基础”的一部分输入给AI让它去补充细节和示例。7.3 Mock数据过于随机无法满足特定测试场景问题Prism的动态Mock数据每次都是随机的但测试有时需要固定的数据如测试一个特定的用户ID。解决在OAS中定义具体示例examples这是最推荐的方式。你可以在Prompt中明确要求“为GET /users/{id}的200响应提供一个具体的示例其中id为‘123’name为‘张三’。” AI会在OAS中写入固定的示例Prism会优先使用它。使用Prism的静态模式启动Prism时使用--static参数它会严格使用OAS中定义的example如果没有则报错。这保证了数据的一致性。自定义响应对于更复杂的需求Prism支持通过配置文件--file来预定义特定请求的响应。但这超出了基础Mock的范围可能需要更复杂的工具或自行开发。7.4 成本与网络依赖问题使用云上的商业AI API如GPT-4会产生费用且依赖网络。解决使用本地模型如前所述ollama 开源代码模型如deepseek-coder,qwen2.5-coder,codellama的组合在API设计这种“结构化生成”任务上表现已经相当不错完全免费且离线可用。缓存结果对于已经确定的设计将最终的OAS文件保存好无需重复生成。AI主要用于创意和初稿阶段。使用更经济的模型对于迭代和微调可以使用更便宜、更快的模型如GPT-3.5-Turbo只在关键设计阶段使用最强模型。MonkeyCode不是一个要取代人类设计师的“黑盒”而是一个强大的“加速器”和“协作者”。它承担了最繁琐的格式编写、示例填充和基础规则检查工作让开发者能更专注于业务逻辑和架构设计本身。通过将这套流程固化下来我们团队在最近两个新项目的API设计阶段效率提升了至少一倍而且产出的规范质量更加统一。最让我满意的是前端同学在需求评审会后几乎立刻就能拿到可联调的接口并行开发变得无比顺畅。如果你也受困于API设计和前后端协作的效率瓶颈不妨试试这套方法相信它会给你带来惊喜。 AI驱动API设计：基于OpenAPI与Mock服务的自动化工作流实践
1. 项目概述当AI成为你的API设计搭档最近在重构一个老项目的后端服务面对几十个混乱不堪、文档缺失的接口我和团队都感到头疼。手动编写Swagger/OpenAPI文档、再搭建Mock服务器来供前端联调这套流程不仅耗时而且一旦需求变更维护文档和Mock数据就成了新的负担。就在我们纠结于工具选型时我尝试了将AI引入到API设计工作流中效果出乎意料。这个项目我称之为“MonkeyCode”核心就是利用AI大语言模型如GPT-4、Claude 3或国内的同级别模型将自然语言描述的需求直接转化为结构严谨的RESTful API接口定义并一键生成可运行的Mock服务。它解决的痛点很明确让API设计阶段从“写文档”变成“提需求”让Mock服务从“手动维护”变成“自动同步”。简单来说MonkeyCode是一个工作流和一系列脚本工具的集合它不依赖于某个特定的AI平台而是将AI作为核心的“翻译官”和“生成器”。你只需要用口语化的方式描述你想要什么接口比如“需要一个用户登录接口接收手机号和密码成功返回token和用户基本信息失败返回错误码”AI就能帮你生成标准的OpenAPI 3.0规范YAML/JSON格式紧接着工具链会基于这份规范自动启动一个Mock服务器前端同学立刻就能拿到真实的URL进行调用和测试。整个过程从想法到可测试的Mock端点可能只需要几分钟。这适合谁呢我认为它非常适合中小型敏捷团队的全栈工程师、后端开发负责人以及独立开发者。尤其是当你在项目初期进行技术方案评审、快速原型验证或者面对大量重复性接口定义工作时MonkeyCode能极大提升效率确保API设计的一致性并让前后端协作的“等待时间”几乎降为零。接下来我将详细拆解这套工作流的核心思路、具体实现以及我趟过的那些坑。2. 核心思路与方案选型为什么是“AI OpenAPI Mock”这个组合在构思MonkeyCode时我评估过几种常见的API设计协作模式。传统上我们可能会用Swagger Editor手动编写YAML或者用Postman的Collection。但这些方式本质上还是“手写”只不过从代码变成了另一种格式的代码。另一种思路是使用像Apifox、Apidog这类一体化协作平台它们功能强大但往往有较强的平台绑定属性且自定义和自动化程度有时不能满足极客需求。我选择“AI OpenAPI Mock”这个技术栈是基于以下几个核心考量2.1 为什么选择OpenAPI规范作为中间枢纽OpenAPI SpecificationOAS是目前RESTful API描述事实上的标准。它有几个不可替代的优势标准化与工具生态丰富OAS是一个机器可读的规范围绕它有海量的工具包括代码生成器Swagger Codegen, OpenAPI Generator、文档生成器Swagger UI, ReDoc、Mock服务器Prism, Stoplight Studio以及校验工具。选择OAS就意味着你接入了整个生态。单一数据源API的设计信息路径、参数、响应体结构被定义在一个文件中。无论是生成文档、Mock数据还是最终的服务端/客户端代码都源于此保证了信息的一致性避免了“文档是文档代码是代码”的割裂问题。人机皆可读YAML格式对开发者相对友好便于人工审查和版本控制如Git。在MonkeyCode中OAS文件是整个流程的“中枢神经”。AI的任务就是生成它后续所有步骤都依赖于它。2.2 为什么用AI来生成OAS而不是手写这源于对开发体验的优化。手写OAS尤其是复杂的嵌套对象和响应示例非常繁琐且容易出错。AI特别是经过代码和自然语言混合训练的大模型在这方面有天然优势理解意图它能将模糊的自然语言需求转化为精确的技术规范。你说“分页列表”它能理解并生成包含page,size,total,items等标准字段的Schema。知识库与最佳实践优秀的模型内化了大量的API设计最佳实践如HTTP状态码的使用、命名规范、数据格式。你可以要求它“遵循RESTful风格”、“使用JSON:API规范”或“采用公司内部的错误码规范”它通常能很好地执行。生成示例数据为每个字段生成合理的Mock值这对于Mock服务至关重要。AI可以根据字段名和类型如username: string生成像“john_doe”这样的示例比单纯的“string”有用得多。2.3 Mock服务器的选择轻量、实时、与OAS无缝集成有了OAS文件我们需要一个能“读懂”它并提供模拟响应的服务器。我选择了Prism由Stoplight团队开发。原因如下专注MockPrism是专业的OAS Mock服务器不像一些全功能平台那样沉重。动态响应它可以根据请求参数和OAS中定义的示例example或Schema动态生成符合规范的响应数据。如果OAS里没有示例它会基于Schema如type: string,format: email生成一个合理的值如“userexample.com”。CLI友好易于自动化Prism可以通过命令行一键启动完美契合我们的自动化脚本流程。支持请求验证它能在Mock的同时验证 incoming request 是否符合OAS定义对于调试很有帮助。注意市面上类似工具还有Mockoon、API Sprout等。选择Prism主要是看中其与OAS标准的贴合度以及动态生成能力。如果你的场景需要更复杂的逻辑响应如根据请求ID返回特定数据可能需要自行封装或选择其他支持自定义响应脚本的工具。综合来看MonkeyCode的架构流水线非常清晰用户输入自然语言需求 - AI引擎生成/补全OAS规范文件 - 工具链读取OAS文件并启动Prism Mock服务器。这个链条中的每个环节都可以替换比如换用不同的AI服务、不同的Mock工具但核心思想不变用AI降低设计门槛用标准规范保证输出质量用自动化工具提升交付速度。3. 环境准备与工具链搭建要让MonkeyCode跑起来你需要准备好几个关键组件。我会以MacOS/Linux环境为例Windows用户可以通过WSL或相应的包管理器获得类似体验。3.1 核心依赖安装首先是Mock服务器Prism的安装。它基于Node.js所以确保你的系统已经安装了Node.js版本14或以上和npm。# 使用npm全局安装Prism npm install -g stoplight/prism-cli # 安装完成后验证安装 prism --version接下来是AI交互的核心。这里有两种主流方式方式一使用OpenAI API或兼容API如Azure OpenAI。这是最直接的方式你需要一个API Key。# 无需安装额外CLI我们将通过编写Python/Node.js脚本调用。 # 以Python为例安装openai库 pip install openai方式二使用本地大模型。如果你注重隐私、成本或网络环境可以部署本地模型。使用ollama是一个极简的选择它能方便地拉取和运行各种开源模型。# 安装ollama请参考官网 https://ollama.com/ 的安装指南 # 拉取一个适合代码生成的模型例如 deepseek-coder 或 qwen2.5-coder ollama pull deepseek-coder:6.7b # 运行模型服务 ollama run deepseek-coder:6.7b # ollama默认会在11434端口提供类OpenAI的API接口非常方便。3.2 项目结构与初始化创建一个项目目录结构如下monkeycode-project/ ├── api-specs/ # 存放生成的OpenAPI规范文件 │ └── petstore.yaml # 示例 ├── scripts/ # 存放自动化脚本 │ ├── generate_spec.py # AI生成OAS的脚本 │ └── start_mock.sh # 启动Mock服务的脚本 ├── .env # 存储API Key等敏感信息记得加入.gitignore └── README.md初始化一个Python虚拟环境是个好习惯cd monkeycode-project python3 -m venv venv source venv/bin/activate # Linux/Mac # venv\Scripts\activate # Windows pip install openai python-dotenv requests在.env文件中配置你的AI服务密钥OPENAI_API_KEYsk-your-secret-key-here # 如果使用本地ollama则配置其base_url # OPENAI_API_BASEhttp://localhost:11434/v1 # OPENAI_API_KEYnot-needed # ollama可能不需要key但某些客户端要求非空3.3 第一个OpenAPI规范模板为了让AI更好地生成内容我们最好提供一个基础模板。这个模板定义了OpenAPI的版本、基础信息以及一些通用的组件如标准错误响应Schema。这能引导AI在正确的框架下填充内容。创建一个api-specs/template.yaml文件openapi: 3.0.3 info: title: MonkeyCode Generated API version: 1.0.0 description: API automatically generated by MonkeyCode with AI. servers: - url: http://localhost:4010 # Prism默认Mock端口 description: Mock server paths: {} # 路径将由AI填充 components: schemas: ErrorResponse: type: object properties: code: type: integer description: 业务错误码 message: type: string description: 错误信息 requestId: type: string description: 请求ID用于追踪 required: - code - message securitySchemes: BearerAuth: type: http scheme: bearer这个模板预先定义了通用的错误响应格式和一个Bearer Token的安全方案AI在生成具体接口时可以直接引用#/components/schemas/ErrorResponse保证所有接口的错误格式统一。4. 核心脚本解析如何让AI理解并生成OAS这是MonkeyCode的“大脑”部分。我们需要编写一个脚本其核心功能是接收用户的需求描述结合基础模板调用AI服务生成或更新一个完整的OpenAPI规范文件。4.1 构建高效的AI提示词Prompt与AI沟通的质量直接决定了输出结果的质量。经过多次试验我总结出一个高效的Prompt结构你是一个专业的API架构师精通OpenAPI 3.0.3规范。请根据以下用户需求生成或补充OpenAPI规范。 【现有规范基础】 {existing_spec_yaml} 【用户需求】 {user_requirement} 【任务要求】 1. 严格遵循RESTful设计原则。 2. 使用JSON作为请求和响应的数据格式。 3. 为每个操作operation提供清晰的summary和description。 4. 为每个请求参数和响应字段提供详细的description。 5. 为每个HTTP状态码至少200成功和4xx/5xx错误提供响应示例example。示例数据应尽可能真实、合理。 6. 合理利用components部分对可复用的Schema如分页结构、用户对象进行定义和引用。 7. 如果需求中涉及身份验证请使用Bearer Token方式securitySchemes中已定义。 请直接输出完整的、可执行的OpenAPI YAML内容不要包含任何解释性文字。这个Prompt做了几件关键事角色设定让AI进入“专家”状态。提供上下文传入现有的规范基础可能是模板也可能是已存在的部分API让AI在此基础上进行增量生成或修改而不是每次都从零开始。明确要求列出了具体、可检查的条目如提供示例、使用components极大地提高了输出的规范性和可用性。格式化指令要求直接输出YAML方便脚本直接捕获。4.2 Python脚本实现generate_spec.py下面是一个使用OpenAI API的脚本示例。如果你使用本地ollama只需将base_url修改为http://localhost:11434/v1并选择对应的模型名如deepseek-coder。import openai import yaml import os from dotenv import load_dotenv import sys # 加载环境变量 load_dotenv() # 配置OpenAI客户端 client openai.OpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_API_BASE, https://api.openai.com/v1) # 默认OpenAI可覆盖为ollama地址 ) def read_yaml_file(filepath): 读取YAML文件内容 try: with open(filepath, r, encodingutf-8) as f: return yaml.safe_load(f) except FileNotFoundError: print(f文件 {filepath} 不存在将使用空基础。) return None def write_yaml_file(filepath, data): 将数据写入YAML文件 with open(filepath, w, encodingutf-8) as f: yaml.dump(data, f, allow_unicodeTrue, sort_keysFalse, default_flow_styleFalse) print(f规范已成功写入: {filepath}) def generate_openapi_spec(user_requirement, base_spec_path, output_spec_path): 核心生成函数 :param user_requirement: 用户需求描述字符串 :param base_spec_path: 现有基础规范文件路径 :param output_spec_path: 输出文件路径 # 1. 读取现有规范 existing_spec read_yaml_file(base_spec_path) existing_spec_yaml yaml.dump(existing_spec, allow_unicodeTrue) if existing_spec else # 2. 构建Prompt prompt f你是一个专业的API架构师精通OpenAPI 3.0.3规范。请根据以下用户需求生成或补充OpenAPI规范。 【现有规范基础】 {existing_spec_yaml} 【用户需求】 {user_requirement} 【任务要求】 1. 严格遵循RESTful设计原则。 2. 使用JSON作为请求和响应的数据格式。 3. 为每个操作operation提供清晰的summary和description。 4. 为每个请求参数和响应字段提供详细的description。 5. 为每个HTTP状态码至少200成功和4xx/5xx错误提供响应示例example。示例数据应尽可能真实、合理。 6. 合理利用components部分对可复用的Schema如分页结构、用户对象进行定义和引用。 7. 如果需求中涉及身份验证请使用Bearer Token方式securitySchemes中已定义。 请直接输出完整的、可执行的OpenAPI YAML内容不要包含任何解释性文字。 # 3. 调用AI模型 try: response client.chat.completions.create( modelos.getenv(OPENAI_MODEL, gpt-4-turbo-preview), # 可配置本地模型如deepseek-coder messages[ {role: system, content: 你是一个输出纯净YAML的OpenAPI规范生成器。}, {role: user, content: prompt} ], temperature0.2, # 温度调低输出更稳定、确定性更高 streamFalse ) ai_output response.choices[0].message.content.strip() # 4. 清理输出AI有时会在YAML前后加yaml标记 if ai_output.startswith(yaml): ai_output ai_output[7:] if ai_output.endswith(): ai_output ai_output[:-3] ai_output ai_output.strip() # 5. 解析并保存YAML generated_spec yaml.safe_load(ai_output) write_yaml_file(output_spec_path, generated_spec) print(生成成功) except openai.APIError as e: print(f调用AI API时出错: {e}) sys.exit(1) except yaml.YAMLError as e: print(f解析AI返回的YAML时出错: {e}) print(AI返回的原始内容) print(ai_output) sys.exit(1) if __name__ __main__: # 示例通过命令行参数或直接赋值获取需求 if len(sys.argv) 1: requirement .join(sys.argv[1:]) else: # 也可以从文件读取或交互式输入 requirement input(请输入你的API需求描述: ) base_spec api-specs/template.yaml # 基础模板 output_spec api-specs/generated_api.yaml # 输出文件 generate_openapi_spec(requirement, base_spec, output_spec)4.3 脚本使用与迭代运行脚本非常简单cd scripts python generate_spec.py “管理一个简单的待办事项Todo系统。需要以下接口1. 创建待办事项POST /todos需要标题和可选描述。2. 获取待办事项列表GET /todos支持分页查询。3. 获取单个待办事项详情GET /todos/{id}。4. 更新待办事项状态PATCH /todos/{id}主要更新完成状态。5. 删除待办事项DELETE /todos/{id}。所有操作都需要Bearer Token认证。”脚本会调用AI生成一个完整的generated_api.yaml文件。你可以打开这个文件查看AI应该已经生成了完整的paths、components.schemas.Todo、components.schemas.TodoList包含分页并为每个接口的200、400、401、404、500等状态码提供了示例响应。实操心得第一次生成的结果可能不完美比如字段类型不对或者示例数据不合理。MonkeyCode的精髓在于“对话式迭代”。你不必手动修改YAML而是可以再次运行脚本将base_spec_path指向刚刚生成的generated_api.yaml然后在user_requirement中提出修改意见例如“在刚才生成的Todo API基础上为创建接口的请求体增加一个priority字段类型为整数枚举值为1低、2中、3高默认为2。同时在获取列表的响应中增加按priority和createdAt倒序排序的说明。” AI会理解现有结构并应用你的修改。5. 一键部署Mock服务与实时测试生成了标准的OpenAPI规范文件后启动Mock服务就变得异常简单。我们编写一个Shell脚本或批处理文件来封装这个命令。5.1 启动脚本start_mock.sh#!/bin/bash # scripts/start_mock.sh SPEC_FILE${1:-../api-specs/generated_api.yaml} # 默认使用生成的API文件 PORT${2:-4010} # 默认端口4010 echo 正在启动Mock服务器使用规范文件: $SPEC_FILE echo Mock服务地址: http://localhost:$PORT prism mock $SPEC_FILE --port $PORT给脚本执行权限并运行chmod x scripts/start_mock.sh cd scripts ./start_mock.sh或者直接指定文件./start_mock.sh ../api-specs/petstore.yaml 8080Prism启动后会在控制台输出可用的端点。它默认会使用OAS文件中servers的URL如果没有则使用http://localhost:[port]。5.2 测试生成的API打开浏览器或使用你喜欢的API测试工具如Postman, curl, httpie获取待办列表GET http://localhost:4010/todos?page1size10创建待办事项curl -X POST http://localhost:4010/todos \ -H Content-Type: application/json \ -H Authorization: Bearer fake-jwt-token-for-mock \ -d {title: 学习MonkeyCode, description: 完成这篇博文}Prism会根据OAS中定义的示例example或Schema返回一个结构正确、数据合理的响应。例如对于GET /todos/{id}如果OAS中定义了响应示例它会返回示例数据如果没有它会根据Schematype: string,format: uuid生成一个随机的UUID作为id。5.3 Mock服务的进阶配置Prism支持一些有用的参数可以整合进启动脚本--dynamic这是默认行为根据Schema生成动态数据。--cors启用CORS头方便前端直接调用。--errors模拟错误响应。例如--errors会随机返回4xx/5xx错误--errors 404,500则只模拟这两种错误。这在测试前端错误处理时非常有用。一个更健壮的启动脚本可能如下#!/bin/bash SPEC_FILE${1:-../api-specs/generated_api.yaml} PORT${2:-4010} DELAY${3:-0} # 模拟网络延迟单位毫秒 echo 启动Mock服务器 (延迟: ${DELAY}ms) prism mock $SPEC_FILE --port $PORT --cors --delay $DELAY6. 工程化与团队协作实践MonkeyCode在个人项目中很好用但要融入团队协作流程还需要一些工程化的考量。6.1 将OAS文件纳入版本控制生成的api-specs/generated_api.yaml应该被提交到Git仓库。这带来了几个好处设计可追溯每次API设计的变更都通过AI生成新的规范文件并提交Git历史记录了设计演进的过程。团队共享前后端开发人员都基于同一份权威的规范文件工作。作为合同这份文件就是前后端之间的“合同”Mock服务和后续的代码生成都基于此减少了沟通歧义。6.2 设计评审流程虽然AI能生成不错的初稿但人工评审必不可少。建议的流程是产品经理或后端开发者提出需求描述。运行MonkeyCode生成初版OAS文件。在Git仓库中发起一个Pull RequestPR将生成的OAS文件变更提交。后端、前端、测试同学在PR中评审这份API设计路径是否合理字段命名是否清晰状态码使用是否正确错误格式是否统一评审意见可以再次作为“用户需求”输入给AI进行迭代修改直到达成一致。合并PR更新主分支的OAS文件。6.3 与CI/CD管道集成你可以在CI持续集成管道中增加一个验证步骤例如语法校验使用swagger-cli或openapi-validator校验生成的OAS文件语法是否正确。风格检查使用spectral一个OpenAPI风格检查工具来强制执行团队的API设计规则如必须提供描述、必须使用ISO8601时间格式等。自动化Mock部署在测试环境中可以自动基于主分支的OAS文件启动一个Prism Mock服务供自动化测试或前端开发环境使用。一个简单的GitHub Actions工作流示例name: Validate OpenAPI Spec on: [pull_request] jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Validate OpenAPI Spec run: | npm install -g apideck/portman # 或者使用其他校验工具 # 对api-specs/目录下的yaml文件进行校验 npx portman --cliOptionsFile portman-config.json7. 常见问题、局限性与应对策略在实际使用MonkeyCode的过程中我遇到了一些典型问题以下是总结和解决方案。7.1 AI生成内容不稳定或不符合预期问题生成的字段类型错误如该用integer用了string示例数据荒谬或遗漏了某些需求点。解决优化Prompt这是最关键的一步。在Prompt中提供更具体的约束例如“所有时间字段必须使用string类型并设置format: date-time”。可以要求AI“先思考再输出”有时能提升逻辑性。提供更详细的上下文在“现有规范基础”中包含你们团队已经定义好的通用组件分页结构、标准响应头等AI会倾向于复用。分步生成不要试图用一个复杂的Prompt生成整个系统。先生成核心的components/schemas数据模型再基于这些模型去生成各个接口的paths。人工微调与迭代接受AI作为“高级助手”的定位。第一次生成完成度能达到70%-80%即可剩下的通过“对话式迭代”逐步修正。将修改需求描述清楚再次运行脚本。7.2 复杂业务逻辑难以描述问题某些接口逻辑复杂涉及条件判断、状态流转单纯用自然语言描述AI可能无法准确转化为API设计。解决拆分需求将复杂接口拆分成多个简单的、原子性的操作。例如“用户下单”可能拆成“创建订单”、“扣减库存”、“支付回调”等多个接口。使用伪代码或序列图辅助描述在需求描述中可以加入简单的伪代码或文字描述的序列图。例如“流程1. 客户端POST /orders。2. 系统验证库存调用内部服务。3. 若库存充足创建订单记录状态为‘待支付’并返回支付URL。4. 库存不足则返回错误。”先设计后生成对于核心复杂接口可以先在白板或设计工具上画出大致的请求响应结构然后将这个结构作为“现有规范基础”的一部分输入给AI让它去补充细节和示例。7.3 Mock数据过于随机无法满足特定测试场景问题Prism的动态Mock数据每次都是随机的但测试有时需要固定的数据如测试一个特定的用户ID。解决在OAS中定义具体示例examples这是最推荐的方式。你可以在Prompt中明确要求“为GET /users/{id}的200响应提供一个具体的示例其中id为‘123’name为‘张三’。” AI会在OAS中写入固定的示例Prism会优先使用它。使用Prism的静态模式启动Prism时使用--static参数它会严格使用OAS中定义的example如果没有则报错。这保证了数据的一致性。自定义响应对于更复杂的需求Prism支持通过配置文件--file来预定义特定请求的响应。但这超出了基础Mock的范围可能需要更复杂的工具或自行开发。7.4 成本与网络依赖问题使用云上的商业AI API如GPT-4会产生费用且依赖网络。解决使用本地模型如前所述ollama 开源代码模型如deepseek-coder,qwen2.5-coder,codellama的组合在API设计这种“结构化生成”任务上表现已经相当不错完全免费且离线可用。缓存结果对于已经确定的设计将最终的OAS文件保存好无需重复生成。AI主要用于创意和初稿阶段。使用更经济的模型对于迭代和微调可以使用更便宜、更快的模型如GPT-3.5-Turbo只在关键设计阶段使用最强模型。MonkeyCode不是一个要取代人类设计师的“黑盒”而是一个强大的“加速器”和“协作者”。它承担了最繁琐的格式编写、示例填充和基础规则检查工作让开发者能更专注于业务逻辑和架构设计本身。通过将这套流程固化下来我们团队在最近两个新项目的API设计阶段效率提升了至少一倍而且产出的规范质量更加统一。最让我满意的是前端同学在需求评审会后几乎立刻就能拿到可联调的接口并行开发变得无比顺畅。如果你也受困于API设计和前后端协作的效率瓶颈不妨试试这套方法相信它会给你带来惊喜。