
GET /api/v1/users/:id【免費(fèi)下載鏈接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto描述簡(jiǎn)要說明這個(gè)端點(diǎn)做什么參數(shù)名稱類型必填說明idstring是用戶 ID響應(yīng)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()這個(gè)模板的設(shè)計(jì)要點(diǎn)值得逐一拆解 - **以 HTTP 方法 路徑作為標(biāo)題**## GET /api/v1/users/:id 這種標(biāo)題既符合 RESTful 習(xí)慣也便于搜索引擎與讀者按端點(diǎn)索引路徑參數(shù)用 :id 占位。 - **參數(shù)表標(biāo)準(zhǔn)化**名稱 / 類型 / 必填 / 說明 四列足以覆蓋大多數(shù)場(chǎng)景更復(fù)雜的場(chǎng)景路徑參數(shù)、查詢參數(shù)、請(qǐng)求體分離見下文倉(cāng)庫(kù)配套模板。 - **多狀態(tài)碼響應(yīng)**同時(shí)給出成功響應(yīng)200與失敗響應(yīng)404 等并保持 JSON 結(jié)構(gòu)一致例如統(tǒng)一用 error message 表達(dá)錯(cuò)誤方便調(diào)用方統(tǒng)一解析。 - **多語(yǔ)言示例**同時(shí)給出 cURL、JavaScript、Python 三種調(diào)用示例覆蓋終端調(diào)試 / 前端調(diào)用 / 后端腳本三類最常見的消費(fèi)方式。 ### 倉(cāng)庫(kù)配套更完整的端點(diǎn)模板 倉(cāng)庫(kù)在 [api-endpoint.md](https://link.gitcode.com/i/2758ba0360f0a62f54d0aebca3f79766) 中提供了該模板的進(jìn)階版在原結(jié)構(gòu)上補(bǔ)充了**認(rèn)證方式、路徑參數(shù)/查詢參數(shù)/請(qǐng)求體分節(jié)、錯(cuò)誤碼體例、限流說明、相關(guān)端點(diǎn)索引**等字段適合生成需要交付給第三方開發(fā)者的正式文檔。其骨架為 - **Authentication**聲明所需認(rèn)證方式例如 Bearer token - **Parameters** 下拆分為 Path Parameters、Query Parameters含默認(rèn)值如 page 默認(rèn) 1、limit 默認(rèn) 20與 Request Body - **Responses** 覆蓋 200 OK、400 Bad RequestVALIDATION_ERROR、404 Not FoundNOT_FOUND等狀態(tài)碼且錯(cuò)誤體統(tǒng)一為 { success, error: { code, message } } - **Examples** 同樣提供 cURL / JavaScript / Python 三種示例 - **Rate Limits**記錄限流策略如認(rèn)證用戶每小時(shí) 1000 次、公開端點(diǎn)每小時(shí) 100 次 - **Related Endpoints**列出關(guān)聯(lián)端點(diǎn)便于導(dǎo)航。 如果需要為單個(gè)函數(shù)而不是 HTTP 端點(diǎn)寫文檔倉(cāng)庫(kù)還提供了 [function-docs.md](https://link.gitcode.com/i/98f2482d8e1b456d1e68136a59287f9f) 模板包含**簽名TypeScript 類型、參數(shù)表、返回值、拋出的異常、基礎(chǔ)/進(jìn)階用法示例、注意事項(xiàng)與 See Also** 等章節(jié)——它與端點(diǎn)模板互補(bǔ)共同構(gòu)成接口文檔的完整表達(dá)體系。 ## 四、源碼級(jí)佐證AST 自動(dòng)提取是如何實(shí)現(xiàn)的 模板定義了長(zhǎng)什么樣而真正從源碼生成靠的是提取邏輯。doc-generator Skill 的同目錄下就帶有一個(gè)真實(shí)的 Python 實(shí)現(xiàn) [generate-docs.py](https://link.gitcode.com/i/ca8f068822c3ab7bed9d93a9bff90a01)它展示了 Skill 如何借助腳本完成機(jī)械化工作、Claude 只負(fù)責(zé)編排的協(xié)作模式。 該腳本的核心是繼承自 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) 關(guān)鍵機(jī)制 1. **基于 AST 而非正則**用 Python 標(biāo)準(zhǔn)庫(kù) ast 解析源碼可正確識(shí)別函數(shù)簽名、參數(shù)、注解與 docstring比正則匹配更健壯 2. **命名約定驅(qū)動(dòng)**只提取以 get_ 或 post_ 開頭的函數(shù)作為端點(diǎn)從源碼結(jié)構(gòu)看這是約定 HTTP 方法前綴的命名風(fēng)格你可以按項(xiàng)目實(shí)際約定修改這一條件 3. **docstring 即文檔源**函數(shù) docstring 被直接作為端點(diǎn)描述ast.get_docstring(node) 會(huì)正確處理引號(hào)與縮進(jìn) 4. **注解提取返回類型**_extract_return_type 用 ast.unparse 還原返回注解表達(dá)式未標(biāo)注時(shí)回退為 Any 5. **參數(shù)列表自動(dòng)抓取**通過 node.args.args 收集形參名無需手寫。 隨后 [generate_markdown_docs](https://link.gitcode.com/i/ca8f068822c3ab7bed9d93a9bff90a01#L31-L42) 把這些結(jié)構(gòu)化的端點(diǎn)數(shù)據(jù)渲染成 Markdown——每個(gè)端點(diǎn)輸出 ## 名稱、docstring、**Parameters**、**Returns** 小節(jié)并以 --- 分隔main 入口[generate-docs.py](https://link.gitcode.com/i/ca8f068822c3ab7bed9d93a9bff90a01#L45-L55)接收源文件路徑、打印生成的文檔 bash python generate-docs.py path/to/api.py 這正是從源代碼生成 API 文檔最直接的機(jī)械化實(shí)現(xiàn)**Claude 負(fù)責(zé)理解上下文與組織最終文檔結(jié)構(gòu)腳本負(fù)責(zé)確定性、可重復(fù)的提取**。你可以將類似腳本放進(jìn) Skill 的 scripts/ 目錄讓 Skill 在需要時(shí)通過 bash 直接執(zhí)行且無需把腳本內(nèi)容載入上下文這正是 Skills 漸進(jìn)式披露的第三層資源加載方式見 [Skills 指南](https://link.gitcode.com/i/1fe7b3b277428a1683640ce2fa40f8f3)。 ## 五、完整生成流程從掃描源碼到產(chǎn)出文檔 將 Skill 的模板規(guī)范、倉(cāng)庫(kù)命令的步驟與配套 agent 組合起來一次完整的 API 文檔生成工作流如下對(duì)應(yīng) [generate-api-docs.md 命令](https://link.gitcode.com/i/3a9734335861d52b1d1f806a34fe5943) 的 6 步流程 1. **掃描 API 端點(diǎn)**定位項(xiàng)目中的接口定義文件例如 /src/api/ 目錄 2. **提取函數(shù)簽名與 JSDoc/docstring**讀取每個(gè)端點(diǎn)的參數(shù)、返回類型與注釋如第三節(jié)模板中的 id: string 參數(shù)表、USER_NOT_FOUND 錯(cuò)誤碼即來源于此 3. **按端點(diǎn)/模塊組織**將提取結(jié)果歸類到 GET /api/v1/users/:id 這樣的條目下 4. **生成帶示例的 Markdown**為每個(gè)端點(diǎn)補(bǔ)齊 cURL、JavaScript、Python 示例 5. **包含請(qǐng)求/響應(yīng) schema**給出請(qǐng)求體與各狀態(tài)碼的 JSON 結(jié)構(gòu) 6. **補(bǔ)充錯(cuò)誤文檔**匯總錯(cuò)誤碼、含義與處理建議。 產(chǎn)出物按 [01-slash-commands 中的流程](https://link.gitcode.com/i/9087a826fef106038f935fa439453e80) 應(yīng)寫入 /docs/api.mdMarkdown 文件并要求包含所有端點(diǎn)的 curl 示例與 TypeScript 類型。你可以在 [doc-refactor.md](https://link.gitcode.com/i/6c06986c92bda72c4731f335cc92927c) 等相鄰命令中看到類似的掃描→提取→組織→輸出模式說明這套工作流在倉(cāng)庫(kù)中是通用范式。 ## 六、與文檔插件體系配合agent、命令與模板 doc-generator 不是孤立存在的。倉(cāng)庫(kù)在 [07-plugins/documentation](https://link.gitcode.com/i/b624a12dee3e41c7586efbc88e946184) 中圍繞文檔生成搭建了一套完整插件可以直接與本文 Skill 協(xié)同 - **子代理 [api-documenter.md](https://link.gitcode.com/i/51db59cf466afae7f5eb71ef1512cc61)**一個(gè)只讀型文檔專家tools: Read, Write, Grep職責(zé)是創(chuàng)建全面 API 文檔——端點(diǎn)文檔、參數(shù)描述、響應(yīng) schema、curl/JS/Python 代碼示例、錯(cuò)誤碼。當(dāng)生成任務(wù)較重時(shí)可以把這個(gè) Skill 放到 context: fork 的子代理上下文中執(zhí)行避免占用主會(huì)話上下文 - **命令 [generate-api-docs.md](https://link.gitcode.com/i/3a9734335861d52b1d1f806a34fe5943) / [generate-readme.md](https://link.gitcode.com/i/55fd15c35818c688fa995d63f7a11788)**把流程固化為可直接 / 調(diào)用的命令 - **模板目錄 [templates](https://link.gitcode.com/i/1ac45c818a2aae5f6e76873117c7aa6c)**包含上文提到的 [api-endpoint.md](https://link.gitcode.com/i/2758ba0360f0a62f54d0aebca3f79766)端點(diǎn)級(jí)與 [function-docs.md](https://link.gitcode.com/i/98f2482d8e1b456d1e68136a59287f9f)函數(shù)級(jí)模板供 Skill 按需加載填充 - **驗(yàn)證命令 [validate-docs.md](https://link.gitcode.com/i/9d3b1a038484d58a986f5546f470ccbc) / [sync-docs.md](https://link.gitcode.com/i/f1500d550ae58638edea05a4413c838f)**用于檢查文檔完整性、同步文檔與代碼變更。 實(shí)踐中推薦的分工是**doc-generator Skill 負(fù)責(zé)按需自動(dòng)觸發(fā) 規(guī)范約束AST 腳本負(fù)責(zé)確定性提取api-endpoint 模板負(fù)責(zé)格式兜底api-documenter 子代理負(fù)責(zé)大規(guī)模重寫任務(wù)**。這種Skill自動(dòng)觸發(fā) 腳本機(jī)械化 模板規(guī)范化 子代理隔離執(zhí)行的組合正是 [Skills 指南](https://link.gitcode.com/i/1fe7b3b277428a1683640ce2fa40f8f3) 所強(qiáng)調(diào)的將腳本、模板與說明打包在一起、標(biāo)準(zhǔn)化流程的典型用法。 ## 七、安裝、調(diào)用與最佳實(shí)踐 ### 安裝位置 將 Skill 目錄含 SKILL.md 與可選的 scripts/、templates/放入以下任一位置即可被自動(dòng)發(fā)現(xiàn) bash # 項(xiàng)目級(jí)推薦可通過 git 共享給團(tuán)隊(duì) .claude/skills/doc-generator/SKILL.md # 個(gè)人級(jí) ~/.claude/skills/doc-generator/SKILL.md【免費(fèi)下載鏈接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto創(chuàng)作聲明:本文部分內(nèi)容由AI輔助生成(AIGC),僅供參考