企业官网建设流程全解析

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

描述

简要说明这个端点做什么

参数

响应

200 成功

{ "id": "usr_123", "name": "John Doe", "email": "john@example.com", "created_at": "2025-01-15T10:30:00Z" }

404 未找到

{ "error": "USER_NOT_FOUND", "message": "User does not exist" }

示例

cURL

curl -X GET "https://api.example.com/api/v1/users/usr_123" \ -H "Authorization: Bearer YOUR_TOKEN"

JavaScript

const user = await fetch('/api/v1/users/usr_123', { headers: { 'Authorization': 'Bearer token' } }).then(r => r.json());

Python

response = 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 Request（`VALIDATION_ERROR`）、404 Not Found（`NOT_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.md`（Markdown 文件），并要求包含所有端点的 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