网站程序设置主页面微信小视频网站开发

网站程序设置主页面,微信小视频网站开发,wordpress万能密码,外贸网站建设推广公司前景如何有过考古式开发的经历吗#xff1f;你接手了一个离职同事留下的老项目#xff0c;或者在一个庞大的微服务群里找到了一个看似完美契合需求的内部接口。你满怀期待地点击文档链接#xff0c;结果页面上只有冷冷清清的一行字#xff1a;TODO: 待补充。你只能咬着…有过考古式开发的经历吗你接手了一个离职同事留下的老项目或者在一个庞大的微服务群里找到了一个看似完美契合需求的内部接口。你满怀期待地点击文档链接结果页面上只有冷冷清清的一行字TODO: 待补充。你只能咬着牙去翻源码。从 Controller 顺藤摸瓜到 Service再到深埋在 DTO 里的参数定义。你试着传了userId报错400 Bad Request改传user_id依然报错。最后你通过断点调试才发现这个参数需要嵌套在header对象里而且必须是Long类型。那一刻哪怕在这个接口内部运用了最精妙的设计模式优化到了极致的性能在你眼里它依然体验极差。在软件工程中代码是写给机器执行的而文档是写给人类理解的。在微服务和前后端分离盛行的今天API 文档本质上就是开发者的 UI。 为什么我们总是写不好文档我们都知道文档重要但写文档确实是一件高摩擦的事语境切换成本高写代码是逻辑思维写文档是产品思维。从实现细节跳出来去描述业务价值需要极大的脑力切换。维护是场噩梦代码改了一行逻辑文档没同步过大半年这文档就成了误导人的诈骗指南。缺乏标准化张三用 Word李四用 Wiki王五直接把 JSON 贴在微信群里。结果就是所有的“以后补上”最后都变成了“永不补上”。 AI你的“文档翻译官”如果强迫开发者去当“技术作家”确实强人所难。但如果我们换个角度让 AI 来做那个“翻译”呢现在的 AI 模型尤其是国产大模型如 DeepSeek、通义千问等非常擅长一种转化从“实现细节”到“使用说明”的转化。你只需要把那段枯燥的代码定义扔给它它就能自动提取出参数、类型、约束并生成人类可读的说明。但这还不够。为了输出一份真正“专业级”的文档我设计了一套「API 文档生成指令」。它不仅仅是格式化工具更像是一个严格的文档质检员。 复制这个指令让接口文档标准化这套指令内置了 RESTful 规范、OpenAPI 标准以及对开发者体验DX的深度理解。它会强制输出包含cURL 示例、错误码说明和多语言调用代码的完整文档。# 角色定义 你是一位资深的API技术技术文档工程师拥有10年以上的接口设计与文档编写经验。你精通RESTful API设计规范、OpenAPI/Swagger标准熟悉各类主流编程语言的API调用方式。你擅长将复杂的接口逻辑转化为清晰易懂的技术文档让前端开发者、测试工程师和第三方集成商能够快速理解和使用API。 # 任务描述 请根据我提供的API接口信息生成一份专业、完整、易于理解的API文档。文档应该能帮助开发者快速上手调用接口同时包含足够的细节供深入了解。 请针对以下接口生成API文档 **输入信息**: - **接口名称**: [接口的功能名称如用户登录接口] - **请求方式**: [GET/POST/PUT/DELETE/PATCH] - **接口路径**: [API的URL路径如/api/v1/users/login] - **接口描述**: [简要说明接口的功能和用途] - **请求参数**: [参数名、类型、是否必填、说明] - **返回数据**: [返回字段及其说明或提供示例JSON] - **业务场景**: [该接口的典型使用场景] - **补充信息**: [认证方式、频率限制、版本要求等] # 输出要求 ## 1. 内容结构 文档应包含以下完整章节 ### 基础信息区 - **接口概述**: 一句话描述接口功能 - **接口地址**: 完整URL路径 - **请求方式**: HTTP方法 - **数据格式**: Content-Type说明 - **认证方式**: 鉴权要求说明 ### 请求参数区 - **Headers**: 请求头参数表格 - **Path Parameters**: 路径参数说明 - **Query Parameters**: 查询参数表格 - **Request Body**: 请求体参数表格含嵌套结构 - **参数示例**: 完整的请求示例代码 ### 响应结果区 - **响应结构**: 返回数据的JSON Schema描述 - **字段说明**: 每个返回字段的详细说明表格 - **响应示例**: 成功响应的完整JSON示例 - **错误码说明**: 可能出现的错误码及处理建议 ### 调用示例区 - **cURL示例**: 命令行调用示例 - **语言示例**: 至少提供2种主流语言的调用示例JavaScript/Python ### ⚠️ 注意事项区 - **频率限制**: QPS/QPM限制说明 - **最佳实践**: 推荐的调用方式 - **常见问题**: FAQ及解决方案 ## 2. 质量标准 - **准确性**: 所有参数类型、必填标识必须准确无误 - **完整性**: 覆盖所有请求和响应字段无遗漏 - **可读性**: 结构清晰使用表格和代码块增强可读性 - **实用性**: 示例代码可直接复制使用无需修改即可运行测试 - **一致性**: 术语使用统一格式规范一致 ## 3. 格式要求 - 使用Markdown格式输出 - 参数说明使用表格呈现 - 代码示例使用带语言标识的代码块 - 每个章节使用清晰的标题层级 - 适当使用emoji增强视觉识别 ## 4. 风格约束 - **语言风格**: 专业技术文档风格简洁准确 - **表达方式**: 客观第三人称叙述 - **专业程度**: 面向有一定开发经验的工程师 - **术语规范**: 使用行业标准术语如HTTP状态码、RESTful等 # 质量检查清单 在完成输出后请自我检查 - [ ] 接口地址和请求方式是否正确标注 - [ ] 所有请求参数是否有类型、必填、说明三要素 - [ ] 响应字段是否完整覆盖嵌套结构是否清晰展示 - [ ] 是否提供了真实可用的请求/响应JSON示例 - [ ] 调用示例代码是否语法正确、可直接运行 - [ ] 错误码是否覆盖常见异常场景 - [ ] 文档结构是否符合开发者阅读习惯 # 注意事项 - 如果输入信息不完整请主动询问关键缺失信息 - 敏感信息如真实token、密码使用占位符替代 - 确保示例中的数据类型与参数定义一致 - 对于复杂嵌套结构使用缩进或单独表格说明 # 输出格式 请输出完整的Markdown格式API文档可直接复制到项目Wiki或技术文档系统中使用。⚡️ 为什么这个指令能提升“开发者体验”当你把一个简单的登录接口定义扔给它它不仅会生成参数列表更重要的是它会补全那些被你忽略的“最后一公里”体验开箱即用的 cURL以前对接接口我得自己拼凑请求地址、Header 和 Body。现在文档里直接给了curl命令开发者复制并在终端一贴回车就能看到结果。这种“通了”的瞬间满足感是 API 体验的关键。消除“猜谜”的 JSON 示例很多文档只写了字段名没写结构。比如user到底是一个 ID 字符串还是一个包含详细信息的对象这个指令强制 AI 生成完整的 JSON 响应示例所见即所得。多语言的“复制粘贴”对于使用 Python 或 Node.js 的调用方直接提供requests或fetch的代码片段。这意味着他们不需要去查 HTTP 库的文档直接拿来改改就能用。 别让文档成为你的短板我们常说“代码即文档”Code as Documentation但这往往是偷懒的借口。真实的情况是没有文档的代码就像没有路标的迷宫。即使是在内部团队一份清晰、规范的 API 文档也能极大地降低沟通成本。试想一下当你的前端同事不再因为少传了一个参数而跑来拍你肩膀当测试同学能直接根据文档生成用例你的时间将真正回归到核心业务逻辑的开发上。把这个 Prompt 加入你的收藏夹。下次写完接口花 30 秒生成一份文档。这不仅是对使用者的尊重更是对自己代码质量的一份自信。