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:
  • •output_format: Format for documentation (default: markdown)
  • •include_examples: 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 current_repository/.claude/api_doc/ 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