api-doc-generator
Use when generating OpenAPI/Swagger API docs from existing code — scans routes/annotations, extracts params and responses, outputs a YAML/JSON spec.
- Installs
- 550
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/wu529778790/shenzjd-skills --skill api-doc-generator- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads api-doc-generator automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
API Doc Generator
从代码自动生成 API 文档，支持 OpenAPI/Swagger 规范。
Overview
扫描项目代码中的路由和接口定义，自动提取参数、返回值、注释，生成符合 OpenAPI 3.0 规范的 YAML 文件和可交互的文档页面。
When to Use
- User wants to generate API documentation
- User mentions OpenAPI, Swagger, or API docs
- User has REST/GraphQL endpoints that need documentation
- User says "生成 API 文档" / "create API docs"
- User inputs
/api-doc-generator
When NOT to Use:
- User only wants to write API descriptions in README
- User wants to test APIs (use testing tools)
- User's project has no HTTP endpoints
- User wants to generate SDK/client code
- User wants to mock APIs (use Mockoon, WireMock)
Core Pattern
Step 1: 检测框架和路由
| 框架 | 检测方式 | 路由提取 |
|---|---|---|
| Express/Koa/Fastify | require('express') / 路由文件 | 扫描 app.get/post/put/delete |
| Next.js API Routes | app/api/ 目录 | 扫描 route.ts 文件 |
| Gin (Go) | r.GET/POST | 扫描 router 注册 |
| Flask/FastAPI (Python) | @app.route / @router | 扫描装饰器 |
| Spring Boot (Java) | @GetMapping / @RestController | 扫描注解 |
# 快速检测
grep -rE "app\.(get|post|put|delete|patch)" --include="*.ts" --include="*.js" --include="*.go" --include="*.py" -l
Step 2: 提取接口信息
对每个路由提取：
- HTTP Method + Path
- 请求参数：query、params、body（从类型定义/JSDoc/注解推断）
- 响应格式：从 return 语句或类型定义推断
- 注释/描述：从代码注释提取
- 认证要求：检查是否有 auth middleware
Step 3: 生成 OpenAPI YAML
使用 templates/openapi.yaml（Handlebars 模板，含 {{variable}} 与 {{#each}} 占位符）作为基础。将提取的接口信息注入对应变量，渲染后输出 openapi.yaml。渲染结果大致如下：
openapi: 3.0.3
info:
title: 项目名 API
version: 1.0.0
paths:
/api/users:
get:
summary: 获取用户列表
parameters: [...]
responses:
'200':
description: 成功
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
Step 4: 生成交互式文档页面（可选）
使用 Swagger UI 或 Redoc 生成可浏览的 HTML 页面：
# 使用 npx 快速预览
npx @redocly/cli preview-docs openapi.yaml
Quick Reference
/api-doc-generator # 扫描当前项目，生成 openapi.yaml
/api-doc-generator --format yaml # 输出 YAML（默认）
/api-doc-generator --format json # 输出 JSON
/api-doc-generator --preview # 生成并预览交互式文档
| 参数 | 说明 | 默认值 |
|---|---|---|
--format | 输出格式 yaml / json | yaml |
--preview | 生成交互式 HTML 文档 | false |
Common Mistakes
| 错误 | 正确做法 | 原因 |
|---|---|---|
| 只扫描一个文件 | 递归扫描所有路由文件 | 可能遗漏接口 |
| 硬编码请求体结构 | 从类型定义推断 | 保持文档与代码一致 |
| 不处理嵌套路由 | 分析路由注册的完整路径 | /api/users/:id 的 :id 需要标注 |
| 忽略错误响应 | 添加 4xx/5xx 响应 | 完整的 API 文档需要错误说明 |
| 忽略认证要求 | 检查 auth middleware | 客户端需要知道哪些接口需要认证 |
FAQ
What does the api-doc-generator skill do?
Use when generating OpenAPI/Swagger API docs from existing code — scans routes/annotations, extracts params and responses, outputs a YAML/JSON spec.
How do I install api-doc-generator?
Run npx skills add https://github.com/wu529778790/shenzjd-skills --skill api-doc-generator in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/api-doc-generator/ (personal) or .claude/skills/api-doc-generator/ (project).
Which AI agents can use api-doc-generator?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is api-doc-generator safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains api-doc-generator?
It is published by wu529778790 in wu529778790/shenzjd-skills. It has 550 recorded installs.
More from wu529778790/shenzjd-skills
docker-build-deploy
wu529778790/shenzjd-skills
Use when containerizing a Node.js app and setting up GitHub Actions CI/CD to build, push to GHCR, and deploy via SSH. Multi-stage build, non-root user, caching.
dependency-audit
wu529778790/shenzjd-skills
Use when auditing project dependencies for security vulnerabilities, outdated packages, or license compliance across npm/yarn/pnpm, pip, go, and cargo.
git-hooks-setup
wu529778790/shenzjd-skills
Use when setting up git hooks (pre-commit, commit-msg, pre-push) with husky or native hooks for linting, formatting, commit conventions, and secret scanning.
db-migration-helper
wu529778790/shenzjd-skills
Use when generating database migration SQL from model or schema changes — compares current vs desired schema, detects diffs, outputs reversible safe migrations.
github-profile-beautifier
wu529778790/shenzjd-skills
Use when creating or improving a GitHub profile README — themed stats cards, project showcase, tech-stack badges, and typing banner. 5 themes, smart project ranking (snake contribution graph needs separate setup).
performance-profiler
wu529778790/shenzjd-skills
Use when profiling a Node/Go/Python project for performance bottlenecks — bundle size, dependency bloat, large files, unused code — and outputting prioritized optimization recommendations.
Popular backend & apis skills
find-skills
vercel-labs/skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
entra-app-registration
microsoft/azure-skills
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.
google-agents-cli-adk-code
google/agents-cli
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).
embedded-captions
heygen-com/hyperframes
Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.
entra-agent-id
microsoft/azure-skills
Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).
neon
neondatabase/agent-skills
Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.