Interface Documentation Generator Assistant

Capabilities

• Interface Analysis: Identifies interface definitions such as functions, class methods, and API endpoints in Python/JS code
• Chinese Document Extraction: Prioritizes extracting Chinese comments and docstrings, supports simplified and traditional Chinese
• Multi-format Output: Markdown, HTML, JSON, supports REST/GraphQL/function interfaces
• Interactive Options: Select detail level (brief/detailed), format, and whether to include examples
• Report Generation: One-click generation of complete Chinese interface reports, saved as timestamped files
• Team-friendly: Concise output, easy for Chinese teams to review and collaborate

Input Requirements

• Code Content: Code strings, file paths, or directories (supports .py, .js, .ts)
• Language Type: python (default), javascript, typescript
• Optional Parameters:

  • detail_level

    : brief/detailed (default: detailed)

  • output_format

    : markdown/html/json (default: markdown)

  • include_examples

    : true/false (default: true)

{
  "code": "def 用户登录(user: str, pwd: str) -> bool:\n    '''用户登录接口\n    参数:\n    - user: 用户名\n    - pwd: 密码\n    返回: 登录成功True'''\n    pass",
  "lang": "python",
  "detail_level": "详细"
}

Output Format

• Main Output: Chinese Markdown report, format:

  接口文档_YYYY-MM-DD_HH-MM-SS.md

• Save Location:

  .claude/interface_docs/

• Content Includes:
  • Interface list and signatures
  • Chinese descriptions/parameters/return values
  • Example calls (if available)
  • Error codes/exception handling
  • Generation metadata

How to Use

Scripts

• interface_analyzer.py

  : Interface definition analyzer, uses AST to parse Python code

• chinese_doc_extractor.py

  : Chinese comment and docstring extractor, supports regex matching of Chinese

• doc_formatter.py

  : Document formatter, supports Markdown/HTML/JSON

• report_generator.py

  : Complete report generator, integrates analysis results and writes to files

Best Practices

1. Code Standards: Use Chinese docstrings for easy automatic extraction
2. Clear Structure: Use standard syntax for interface definitions, avoid excessive nesting
3. Provide Examples: Include call examples in code to improve documentation quality
4. Module-wise Analysis: Process large projects by directories to avoid single overload
5. Review Output: Manually add business context after automatic generation

Limitations

• Mainly supports Python/JS/TS; complex languages require manual adjustments
• Depends on code comment quality; only extracts signatures when there are no comments
• Binary interfaces of non-dynamic languages are not supported
• Large codebases are recommended to be processed in batches