API Documentation Generator

This skill automatically generates OpenAPI-compliant documentation from code files. It parses interface definitions, API endpoints, and related information to create comprehensive, readable API documentation that follows OpenAPI specification standards.

Capabilities

• File Parsing: Parse interface/API information from files or directories
• OpenAPI Compliance: Generate documentation that complies with OpenAPI specification (https://swagger.io/specification/)
• Timestamp Management: Automatically include timestamps in documentation files
• Directory Scanning: Process multiple files in a directory structure
• Validation: Validate generated documentation against OpenAPI standards
• Multiple Formats: Support for various code file types (Python, JavaScript, TypeScript, etc.)

Input Requirements

• File or directory path: Path to the file or directory containing API/interface definitions
• Supported file types: Python (.py), JavaScript (.js), TypeScript (.ts), JSON (.json), YAML (.yaml, .yml)
• Optional parameters:

- outputformat: Format for documentation (default: markdown) - includeexamples: Whether to include example requests/responses (default: true) - validate_openapi: Validate against OpenAPI specification (default: true)

Output Formats

• Primary output: Markdown file with timestamp format: YYYY-MM-DD_HH-MM-SS.md
• Location: Saved to currentrepository/.claude/apidoc/ directory
• Content: OpenAPI-compliant documentation with:

- API title and description - Endpoint definitions - Request/response schemas - Authentication information - Example usage - Error codes and responses - Timestamp and generation metadata

How to Use

"Generate API documentation from the src/api/ directory" "Parse this Python file and create OpenAPI documentation" "Create API documentation for the endpoints in this TypeScript file"

Scripts

• api_parser.py: Main module for parsing API information from files
• openapi_generator.py: Generates OpenAPI-compliant documentation
• file_handler.py: Handles file operations and directory scanning

Best Practices

1. File Organization: Keep API-related files in structured directories
2. Clear Naming: Use descriptive names for endpoints and parameters
3. Consistent Formatting: Follow consistent code formatting for better parsing
4. Comments: Include clear comments in code for better documentation generation
5. Validation: Always validate generated documentation against OpenAPI standards

Limitations

• Requires properly formatted code with clear interface definitions
• Complex nested structures may require manual review
• Some framework-specific annotations may not be fully parsed
• Generated documentation quality depends on source code clarity
• Large directories may take longer to process