api-document-generator

Parses interface/API information from files or directories and generates OpenAPI-compliant documentation with timestamps

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️2downloads

When & Why to Use This Skill

The API Document Generator is a specialized Claude skill designed to automate the creation of OpenAPI-compliant documentation directly from source code. By parsing interface definitions and API endpoints across multiple programming languages like Python, JavaScript, and TypeScript, it generates structured, timestamped, and validated documentation. This tool significantly reduces manual documentation effort, ensures consistency with the codebase, and maintains high standards for API specifications.

Use Cases

  • Automated Documentation Generation: Quickly transform a directory of source code into comprehensive OpenAPI/Swagger documentation without manual entry.
  • Legacy Code Mapping: Parse existing or legacy codebases to extract API structures and generate standardized documentation for better maintenance.
  • Development Workflow Integration: Use the skill during the development cycle to ensure API references are updated and validated against the latest code changes.
  • Cross-Team Collaboration: Provide frontend developers and external partners with accurate, timestamped API specifications to facilitate seamless integration and reduce communication overhead.
nameapi-document-generator
descriptionParses interface/API information from files or directories and generates OpenAPI-compliant documentation with timestamps

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