api-docs-gen

What This Skill Does

The api-docs-gen skill is an automated documentation engine designed to bridge the gap between undocumented route files and professional-grade API specifications. By scanning your existing codebase, it intelligently parses HTTP routes, request parameters, and response structures. It utilizes the GPT-4o-mini model to transform raw code into human-readable Markdown or machine-readable OpenAPI 3.0 specifications. This eliminates the tedious manual task of writing technical documentation, ensuring your API contracts stay synchronized with your implementation.

Installation

To integrate this skill into your OpenClaw environment, use the provided installation command in your terminal:

clawhub install openclaw/skills/skills/lxgicstudios/api-docs-gen

Ensure you have Node.js 18+ installed on your system. Note that since this skill leverages AI to interpret your code structure, it requires an OPENAI_API_KEY to be set in your environment variables to perform the inference process successfully.

Use Cases

This skill is indispensable for scenarios involving legacy code maintenance, rapid MVP development, or team onboarding. If you have inherited a project with no documentation, api-docs-gen provides instant clarity. For startups, it enables quick generation of Swagger UI dashboards to facilitate client-side integration. It is also an excellent tool for CI/CD pipelines, allowing teams to automate the regeneration of documentation whenever routes are modified, ensuring that internal documentation never becomes obsolete.

Example Prompts

1. "Generate clean Markdown documentation for all routes found in the ./src/v1/routes directory and save it to API_REFERENCE.md."
2. "Analyze my express route files in ./api and output a standard OpenAPI 3.0 YAML spec for our frontend team."
3. "Scan the ./controllers folder and create an API document, using TypeScript types to infer the request body schemas."

Tips & Limitations

• Tip: Organize your routes in consistent directories to help the agent interpret your structure more accurately.
• Tip: Use TypeScript interfaces; the AI model excels at extracting types, resulting in significantly more detailed documentation than raw JavaScript.
• Limitation: The skill provides a draft. While it is highly accurate at structure, you should always review the generated descriptions to ensure they capture the business logic and intent behind your endpoints correctly.
• Constraint: Ensure your route files are reachable by the npx runner and your environment variable is correctly exported before execution.