api-documenting
Scannednpx machina-cli add skill huangjia2019/claude-code-engineering/api-documenting --openclawAPI Documentation Generator
Generate comprehensive API documentation from source code.
Quick Reference
For common documentation patterns, see PATTERNS.md.
Documentation Standards
See STANDARDS.md for our documentation conventions.
Process
Step 1: Identify API Endpoints
Look for:
- Route definitions (Express, FastAPI, etc.)
- Controller methods
- Handler functions
Step 2: Extract Information
For each endpoint, extract:
- HTTP method (GET, POST, PUT, DELETE, etc.)
- Path/route
- Parameters (path, query, body)
- Request/response schemas
- Authentication requirements
Step 3: Generate Documentation
Use the template in templates/endpoint.md for consistent formatting.
Step 4: Create Overview
Generate an index of all endpoints with the template in templates/index.md.
Output Formats
Markdown (Default)
Generate markdown documentation suitable for README or docs site.
OpenAPI/Swagger
If requested, generate OpenAPI 3.0 spec. See templates/openapi.yaml for structure.
Examples
See EXAMPLES.md for sample inputs and outputs.
Scripts
To auto-detect routes in common frameworks:
python scripts/detect_routes.py <source_directory>
To validate generated OpenAPI spec:
./scripts/validate_openapi.sh <spec_file>
Source
git clone https://github.com/huangjia2019/claude-code-engineering/blob/main/04-Skills/projects/02-progressive-skill/.claude/skills/api-documenting/SKILL.mdView on GitHub Overview
api-documenting automates the creation of API documentation by extracting endpoints, methods, parameters, and schemas from source code. It supports both Markdown-based docs for README/docs and OpenAPI/Swagger specs, following centralized templates and standards to ensure consistency.
How This Skill Works
The tool scans the codebase to identify API endpoints by parsing routes, controllers, and handlers. It then extracts HTTP method, path, parameters, and request/response schemas, and renders the results using templates like templates/endpoint.md and templates/index.md to produce a coherent documentation set. Output can be produced as Markdown or OpenAPI 3.0 spec, leveraging templates/openapi.yaml when OpenAPI is requested.
When to Use It
- Document a REST API built with Express, FastAPI, or similar frameworks.
- Generate an API reference and endpoint docs from existing code.
- Create or update an OpenAPI/Swagger specification for alignment with clients.
- Onboard new developers by providing a consistent API docs suite.
- Automate docs generation during refactors or API changes.
Quick Start
- Step 1: Detect routes in your codebase: python scripts/detect_routes.py <source_directory>
- Step 2: Generate endpoint docs and the index using templates/endpoint.md and templates/index.md
- Step 3: Export Markdown or OpenAPI: choose Markdown for README/docs or OpenAPI (templates/openapi.yaml) and run validation if needed
Best Practices
- Reference and align with PATTERNS.md and STANDARDS.md to keep formatting uniform.
- Use templates/endpoint.md for consistent endpoint entries and templates/index.md for a comprehensive overview.
- Regularly validate OpenAPI outputs with validate_openapi.sh to ensure spec correctness.
- Keep schemas in sync with source code changes to avoid drift.
- Run the route-detection script (detect_routes.py) on updated codebases to refresh docs.
Example Use Cases
- Document all Express routes in a Node.js microservice and publish a Markdown API reference.
- Generate an OpenAPI 3.0 spec for a FastAPI app from its codebase.
- Create an index of endpoints for a multi-service portal using templates/index.md.
- Update API docs automatically after adding new routes via detect_routes.py.
- Validate the produced OpenAPI spec with validate_openapi.sh before deployment.
