GET /api/v1/users/:id

GET /api/v1/users/:id【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto描述简要说明这个端点做什么参数名称类型必填说明idstring是用户 ID响应200 成功{ id: usr_123, name: John Doe, email: johnexample.com, created_at: 2025-01-15T10:30:00Z }404 未找到{ error: USER_NOT_FOUND, message: User does not exist }示例cURLcurl -X GET https://api.example.com/api/v1/users/usr_123 \ -H Authorization: Bearer YOUR_TOKENJavaScriptconst user await fetch(/api/v1/users/usr_123, { headers: { Authorization: Bearer token } }).then(r r.json());Pythonresponse requests.get( https://api.example.com/api/v1/users/usr_123, headers{Authorization: Bearer token} ) user response.json()这个模板的设计要点值得逐一拆解 - **以 HTTP 方法 路径作为标题**## GET /api/v1/users/:id 这种标题既符合 RESTful 习惯也便于搜索引擎与读者按端点索引路径参数用 :id 占位。 - **参数表标准化**名称 / 类型 / 必填 / 说明 四列足以覆盖大多数场景更复杂的场景路径参数、查询参数、请求体分离见下文仓库配套模板。 - **多状态码响应**同时给出成功响应200与失败响应404 等并保持 JSON 结构一致例如统一用 error message 表达错误方便调用方统一解析。 - **多语言示例**同时给出 cURL、JavaScript、Python 三种调用示例覆盖终端调试 / 前端调用 / 后端脚本三类最常见的消费方式。 ### 仓库配套更完整的端点模板 仓库在 [api-endpoint.md](https://link.gitcode.com/i/2758ba0360f0a62f54d0aebca3f79766) 中提供了该模板的进阶版在原结构上补充了**认证方式、路径参数/查询参数/请求体分节、错误码体例、限流说明、相关端点索引**等字段适合生成需要交付给第三方开发者的正式文档。其骨架为 - **Authentication**声明所需认证方式例如 Bearer token - **Parameters** 下拆分为 Path Parameters、Query Parameters含默认值如 page 默认 1、limit 默认 20与 Request Body - **Responses** 覆盖 200 OK、400 Bad RequestVALIDATION_ERROR、404 Not FoundNOT_FOUND等状态码且错误体统一为 { success, error: { code, message } } - **Examples** 同样提供 cURL / JavaScript / Python 三种示例 - **Rate Limits**记录限流策略如认证用户每小时 1000 次、公开端点每小时 100 次 - **Related Endpoints**列出关联端点便于导航。 如果需要为单个函数而不是 HTTP 端点写文档仓库还提供了 [function-docs.md](https://link.gitcode.com/i/98f2482d8e1b456d1e68136a59287f9f) 模板包含**签名TypeScript 类型、参数表、返回值、抛出的异常、基础/进阶用法示例、注意事项与 See Also** 等章节——它与端点模板互补共同构成接口文档的完整表达体系。 ## 四、源码级佐证AST 自动提取是如何实现的 模板定义了长什么样而真正从源码生成靠的是提取逻辑。doc-generator Skill 的同目录下就带有一个真实的 Python 实现 [generate-docs.py](https://link.gitcode.com/i/ca8f068822c3ab7bed9d93a9bff90a01)它展示了 Skill 如何借助脚本完成机械化工作、Claude 只负责编排的协作模式。 该脚本的核心是继承自 ast.NodeVisitor 的 APIDocExtractor 类[generate-docs.py](https://link.gitcode.com/i/ca8f068822c3ab7bed9d93a9bff90a01#L5-L28) python class APIDocExtractor(ast.NodeVisitor): Extract API documentation from Python source code. def __init__(self): self.endpoints [] def visit_FunctionDef(self, node): Extract function documentation. if node.name.startswith(get_) or node.name.startswith(post_): doc ast.get_docstring(node) endpoint { name: node.name, docstring: doc, params: [arg.arg for arg in node.args.args], returns: self._extract_return_type(node), } self.endpoints.append(endpoint) self.generic_visit(node) 关键机制 1. **基于 AST 而非正则**用 Python 标准库 ast 解析源码可正确识别函数签名、参数、注解与 docstring比正则匹配更健壮 2. **命名约定驱动**只提取以 get_ 或 post_ 开头的函数作为端点从源码结构看这是约定 HTTP 方法前缀的命名风格你可以按项目实际约定修改这一条件 3. **docstring 即文档源**函数 docstring 被直接作为端点描述ast.get_docstring(node) 会正确处理引号与缩进 4. **注解提取返回类型**_extract_return_type 用 ast.unparse 还原返回注解表达式未标注时回退为 Any 5. **参数列表自动抓取**通过 node.args.args 收集形参名无需手写。 随后 [generate_markdown_docs](https://link.gitcode.com/i/ca8f068822c3ab7bed9d93a9bff90a01#L31-L42) 把这些结构化的端点数据渲染成 Markdown——每个端点输出 ## 名称、docstring、**Parameters**、**Returns** 小节并以 --- 分隔main 入口[generate-docs.py](https://link.gitcode.com/i/ca8f068822c3ab7bed9d93a9bff90a01#L45-L55)接收源文件路径、打印生成的文档 bash python generate-docs.py path/to/api.py 这正是从源代码生成 API 文档最直接的机械化实现**Claude 负责理解上下文与组织最终文档结构脚本负责确定性、可重复的提取**。你可以将类似脚本放进 Skill 的 scripts/ 目录让 Skill 在需要时通过 bash 直接执行且无需把脚本内容载入上下文这正是 Skills 渐进式披露的第三层资源加载方式见 [Skills 指南](https://link.gitcode.com/i/1fe7b3b277428a1683640ce2fa40f8f3)。 ## 五、完整生成流程从扫描源码到产出文档 将 Skill 的模板规范、仓库命令的步骤与配套 agent 组合起来一次完整的 API 文档生成工作流如下对应 [generate-api-docs.md 命令](https://link.gitcode.com/i/3a9734335861d52b1d1f806a34fe5943) 的 6 步流程 1. **扫描 API 端点**定位项目中的接口定义文件例如 /src/api/ 目录 2. **提取函数签名与 JSDoc/docstring**读取每个端点的参数、返回类型与注释如第三节模板中的 id: string 参数表、USER_NOT_FOUND 错误码即来源于此 3. **按端点/模块组织**将提取结果归类到 GET /api/v1/users/:id 这样的条目下 4. **生成带示例的 Markdown**为每个端点补齐 cURL、JavaScript、Python 示例 5. **包含请求/响应 schema**给出请求体与各状态码的 JSON 结构 6. **补充错误文档**汇总错误码、含义与处理建议。 产出物按 [01-slash-commands 中的流程](https://link.gitcode.com/i/9087a826fef106038f935fa439453e80) 应写入 /docs/api.mdMarkdown 文件并要求包含所有端点的 curl 示例与 TypeScript 类型。你可以在 [doc-refactor.md](https://link.gitcode.com/i/6c06986c92bda72c4731f335cc92927c) 等相邻命令中看到类似的扫描→提取→组织→输出模式说明这套工作流在仓库中是通用范式。 ## 六、与文档插件体系配合agent、命令与模板 doc-generator 不是孤立存在的。仓库在 [07-plugins/documentation](https://link.gitcode.com/i/b624a12dee3e41c7586efbc88e946184) 中围绕文档生成搭建了一套完整插件可以直接与本文 Skill 协同 - **子代理 [api-documenter.md](https://link.gitcode.com/i/51db59cf466afae7f5eb71ef1512cc61)**一个只读型文档专家tools: Read, Write, Grep职责是创建全面 API 文档——端点文档、参数描述、响应 schema、curl/JS/Python 代码示例、错误码。当生成任务较重时可以把这个 Skill 放到 context: fork 的子代理上下文中执行避免占用主会话上下文 - **命令 [generate-api-docs.md](https://link.gitcode.com/i/3a9734335861d52b1d1f806a34fe5943) / [generate-readme.md](https://link.gitcode.com/i/55fd15c35818c688fa995d63f7a11788)**把流程固化为可直接 / 调用的命令 - **模板目录 [templates](https://link.gitcode.com/i/1ac45c818a2aae5f6e76873117c7aa6c)**包含上文提到的 [api-endpoint.md](https://link.gitcode.com/i/2758ba0360f0a62f54d0aebca3f79766)端点级与 [function-docs.md](https://link.gitcode.com/i/98f2482d8e1b456d1e68136a59287f9f)函数级模板供 Skill 按需加载填充 - **验证命令 [validate-docs.md](https://link.gitcode.com/i/9d3b1a038484d58a986f5546f470ccbc) / [sync-docs.md](https://link.gitcode.com/i/f1500d550ae58638edea05a4413c838f)**用于检查文档完整性、同步文档与代码变更。 实践中推荐的分工是**doc-generator Skill 负责按需自动触发 规范约束AST 脚本负责确定性提取api-endpoint 模板负责格式兜底api-documenter 子代理负责大规模重写任务**。这种Skill自动触发 脚本机械化 模板规范化 子代理隔离执行的组合正是 [Skills 指南](https://link.gitcode.com/i/1fe7b3b277428a1683640ce2fa40f8f3) 所强调的将脚本、模板与说明打包在一起、标准化流程的典型用法。 ## 七、安装、调用与最佳实践 ### 安装位置 将 Skill 目录含 SKILL.md 与可选的 scripts/、templates/放入以下任一位置即可被自动发现 bash # 项目级推荐可通过 git 共享给团队 .claude/skills/doc-generator/SKILL.md # 个人级 ~/.claude/skills/doc-generator/SKILL.md【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考