Task Objectives
InterfaceDataDocGenerator is an intelligent interface and data documentation generator that helps you quickly generate professional API interface documentation, database design documentation, and communication protocol specifications.
Core Value:
- 🚀 Rapid Generation: Automatically generate complete technical documentation based on architecture documents
- 📋 Rich Templates: Supports multiple document types (API/database/protocol)
- 🔧 Comprehensive Tools: Provides format validation scripts to ensure document quality
- 📚 Comprehensive Technology: Supports multiple programming languages and architecture frameworks
- ✅ Quality Assurance: Completeness verification and standards compliance analysis
Quick Start (5 minutes)
1. Generate API Interface Documentation
# 智能体分析接口需求并生成文档
# 参考 references/api-doc-template.md 模板
# 生成 OpenAPI 3.0 格式或 Postman Collection 格式
2. Generate Database Design Documentation
# 智能体分析数据模型并生成文档
# 参考 references/db-doc-template.md 模板
# 包含表结构、数据字典、索引策略
3. Validate Document Format
# 验证 OpenAPI 格式
python scripts/validate_openapi.py openapi.yaml
# 验证 Protobuf 格式
python scripts/validate_protobuf.proto schema.proto
# 验证 SQL DDL 语法
python scripts/validate_sql.py schema.sql
Done! Now you have interface documentation, database documentation, and communication protocol documentation in standard format.
Core Capabilities
1. Automatic Document Generation ⭐⭐⭐⭐⭐
Trigger Scenarios: When starting a new project or needing to quickly generate technical documentation
Input: Architecture documents, requirement descriptions, or interface lists
Output: Markdown documents in standard format
Supported Document Types:
- API interface documentation (OpenAPI 3.0, Postman Collection)
- Database design documentation (table structures, data dictionaries, indexes)
- Communication protocol documentation (WebSocket, Protobuf, FlatBuffers)
2. Analysis and Optimization of Existing Documentation ⭐⭐⭐⭐⭐
Trigger Scenarios: When existing technical documentation needs to be reviewed and optimized
Analysis Dimensions:
- Completeness check (whether all required sections are included)
- Standards compliance check (naming conventions, field types, constraint definitions)
- Format validation (OpenAPI, Protobuf, SQL syntax)
- Optimization suggestions (data structure design, index optimization)
3. Multi-language and Multi-architecture Support ⭐⭐⭐⭐
Trigger Scenarios: When documentation needs to be generated for different technology stacks
Supported Languages/Frameworks:
- Backend: Java/SpringBoot, Go/Gin, Python/Django/Flask/FastAPI, Node.js/Express/NestJS
- Frontend: React, Vue, Angular, Svelte, Next.js, Nuxt.js
- Databases: MySQL, PostgreSQL, Oracle, MongoDB
- Protocols: RESTful, GraphQL, WebSocket, gRPC
4. Multi-terminal Difference Management ⭐⭐⭐⭐
Trigger Scenarios: When differentiated documentation needs to be generated for different terminals
Supported Terminals:
- Web (complete fields, pagination information, permission markers)
- Mobile (simplified fields, reduced nesting, compressed data)
- Mini Programs (compatibility considerations, avoid using the latest features)
5. Requirement Change Analysis ⭐⭐⭐
Trigger Scenarios: When analyzing the scope of impact after requirement changes
Analysis Content:
- Compare document differences before and after changes
- Identify affected interfaces/tables/protocols
- Provide compatibility suggestions
- Assess scope of impact (technical/development/testing/user experience)
6. Completeness verification ⭐⭐⭐⭐
Trigger scenarios: When ensuring quality after document generation
Checklist:
- API documentation: request parameters, response structure, error codes, authentication description
- Database documentation: table structure, data dictionary, index strategy
- Protocol documentation: connection establishment, message format, error handling
Usage examples
Scenario 1: Generate RESTful API documentation (recommended)
Suitable for frontend-backend projects that need API interface documentation.
Execution flow:
- The agent analyzes the interface list and business logic provided by the user
- Refer to
references/api-doc-template.mdto generate complete documentation - Call
scripts/validate_openapi.pyto validate YAML format
Key points:
- Include methods such as GET/POST/PUT/DELETE
- Define request parameters (Path/Query/Body/Headers)
- Provide success/failure response examples
- Explain the JWT authentication method
Verification results: ✅ API documentation has been generated and verified
Scenario 2: Optimize existing database documentation
Suitable for analyzing existing database design documentation and providing optimization suggestions.
Execution flow:
- The agent reads the database design documentation provided by the user
- Call
scripts/validate_sql.pyto validate DDL syntax - Analyze index strategy, field types, constraint definitions
- Provide optimization suggestions (such as adding composite indexes, optimizing field lengths)
Key points:
- Check whether primary keys, foreign keys, and unique constraints are complete
- Analyze whether indexes cover common query scenarios
- Verify whether field types are reasonable (such as VARCHAR length)
- Provide suggestions for the completeness of the data dictionary
Verification results: ✅ Database documentation has been optimized
Scenario 3: Define real-time communication protocol for games
Suitable for designing WebSocket + Protobuf communication protocols for multiplayer online games.
Execution flow:
- The agent clarifies the game type and communication requirements with the user
- Refer to
references/protocol-template.mdandreferences/protobuf-guide.md - Generate .proto definition files and WebSocket message format
- Call
scripts/validate_protobuf.pyto validate syntax
Key points:
- Define message IDs and command codes (such as CMD_LOGIN, CMD_MOVE)
- Explain the heartbeat mechanism and timeout disconnection strategy
- Provide error handling and rate limiting rules
- Include complete request/response examples
Verification results: ✅ Communication protocol has been defined and verified
Scenario 4: Handle multi-platform differences
Suitable for generating differentiated documentation for Web, mobile, and mini programs.
Execution flow:
- Identify multi-platform requirements (Web, mobile, mini programs)
- Define different response fields for different platforms
- Annotate field difference explanations
- Provide interface version numbers for different platforms
Key points:
- Web: return complete fields, pagination information, permission markers
- Mobile: streamlined fields, reduced nesting levels, compressed data volume
- Mini Program: compatibility considerations (e.g., avoid using the latest features)
Inspection results: ✅ Multi-platform differentiated documentation has been generated
Workflow
Simplified process
1. 需求分析 → 2. 文档生成 → 3. 格式验证 → 4. 完整性校验
Detailed process
Step 1: Consult information
-
Requirements analysis and clarification
- Ask about the target language/architecture (e.g., Java/SpringBoot, Go/Gin, Python/Django, etc.)
- Confirm the types of documentation to generate (API/database/protocol, or all)
- Clarify multi-platform requirements (Web, mobile, Mini Program, etc.)
- If an architecture document or requirements document is provided, read and extract key information
-
Information supplementation and search(if encountering an unfamiliar architecture)
- Use search tools to find best practices and specifications for the target language/architecture
- Obtain interface definition standards for specific frameworks (e.g., SpringBoot's RESTful specifications)
- Understand the characteristics of the target database (MySQL/PostgreSQL/Oracle, etc.)
Step 2: Execute operations
-
Document generation
- API interface documentation:
- Refer to
references/api-doc-template.mdtemplate structure - Generate OpenAPI 3.0 format or Postman Collection format
- Include: basic information, request parameters, response structure, error codes, authentication methods, multi-platform differences
- Use
scripts/validate_openapi.pyto validate format correctness
- Refer to
- Database design documentation:
- Refer to
references/db-doc-template.mdtemplate structure - Generate table structure list, data dictionary, indexing strategy, relationship diagram
- Use
scripts/validate_sql.pyto validate DDL syntax correctness
- Refer to
- Protocol and communication specifications:
- Refer to
references/protocol-template.mdtemplate structure - Choose WebSocket or binary protocol (Protobuf/FlatBuffers) based on the scenario
- Generate IDL definition files, message frame structure, business instruction set
- Use
scripts/validate_protobuf.pyto validate .proto file syntax
- Refer to
- API interface documentation:
-
Integrity verification
- Check whether the documentation contains all required sections
- Confirm the completeness of sample data
- Verify consistency of format specifications
Step 3: Inspection and acceptance
-
Format validation
- Use
scripts/validate_openapi.pyto validate OpenAPI format - Use
scripts/validate_protobuf.pyto validate Protobuf format - Use
scripts/validate_sql.pyto validate SQL syntax
- Use
-
Integrity check
- API documentation: request parameters, response structure, error codes, authentication description
- Database documentation: table structure, data dictionary, indexing strategy
- Protocol documentation: connection establishment, message format, error handling
-
Compliance analysis
- Check whether naming conventions, field types, and constraint definitions comply with best practices
- Provide optimization suggestions
Resource index
Format validation scripts
| Scripts | Purpose |
|---|---|
scripts/validate_openapi.py |
Validate OpenAPI 3.0/YAML format |
scripts/validate_protobuf.py |
Validate Protobuf .proto file syntax |
scripts/validate_sql.py |
Validate SQL DDL syntax correctness |
Document template
| Template | Purpose |
|---|---|
references/api-doc-template.md |
Reference when generating API interface documentation |
references/db-doc-template.md |
Reference when generating database design documentation |
references/protocol-template.md |
Reference when generating protocol and communication specifications |
Technical reference
| Documentation | Purpose |
|---|---|
references/openapi-cheatsheet.md |
Consult when writing OpenAPI specifications |
references/protobuf-guide.md |
Consult when using the Protobuf protocol |
references/websocket-guide.md |
Consult when defining the WebSocket protocol |
Command quick reference
# 验证 OpenAPI 格式
python scripts/validate_openapi.py openapi.yaml
# 验证 Protobuf 格式
python scripts/validate_protobuf.py schema.proto
# 验证 SQL DDL 语法
python scripts/validate_sql.py schema.sql
Frequently Asked Questions (FAQ)
Q1: How do I determine which document template to use?
A: Choose according to your needs:
- Need to define API interfaces → use
references/api-doc-template.md - Need to design database table structures → use
references/db-doc-template.md - Need to define communication protocols → use
references/protocol-template.md
Q2: What should I do if a validation script fails?
A: Check the following points:
- Whether the file path is correct
- Whether the file format conforms to the specification (YAML/JSON/SQL)
- Whether the dependency packages are installed (pyyaml, jsonschema, protobuf)
Q3: How do I handle multi-client differences?
A: Clearly annotate in the documentation:
- Define different response fields for different clients
- Annotate field difference descriptions
- Provide interface version numbers for different clients
Q4: How do I update the documentation after requirements change?
A: Use the requirement change analysis feature:
- Compare the documentation differences before and after the change
- Analyze the scope of impact (which interfaces/tables/protocols are affected)
- Provide compatibility suggestions
Notes
- Format validation priority: Only call scripts when format validation is needed; document generation is mainly completed by the agent
- Knowledge completion: When encountering an unfamiliar tech stack, use search tools to supplement information
- Completeness assurance: Ensure the documentation contains complete examples and error code descriptions
- Multi-client differences: Multi-client differences must be clearly annotated to avoid confusion
- Change analysis: When requirements change, analyze the scope of impact and provide compatibility suggestions
- Best practices: Follow the best practices and specifications of the target language/architecture
- Naming conventions: Ensure naming conventions, field types, and constraint definitions conform to standards
Prerequisites
Dependency description
Dependency packages and versions required by the scripts:
pyyaml>=6.0
jsonschema>=4.17.0
protobuf>=4.21.0
Last updated: 2026-03-06
Version: v1.0.0
Status: ✅ Available