SuperAPI AI Directory

interface-data-doc-generator

Coding & development

View repository

Updated 10-15 17:12

About this skill

InterfaceDataDocGenerator - Interface and Data Documentation Generator

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:

  1. The agent analyzes the interface list and business logic provided by the user
  2. Refer to references/api-doc-template.md to generate complete documentation
  3. Call scripts/validate_openapi.py to 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:

  1. The agent reads the database design documentation provided by the user
  2. Call scripts/validate_sql.py to validate DDL syntax
  3. Analyze index strategy, field types, constraint definitions
  4. 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:

  1. The agent clarifies the game type and communication requirements with the user
  2. Refer to references/protocol-template.md and references/protobuf-guide.md
  3. Generate .proto definition files and WebSocket message format
  4. Call scripts/validate_protobuf.py to 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:

  1. Identify multi-platform requirements (Web, mobile, mini programs)
  2. Define different response fields for different platforms
  3. Annotate field difference explanations
  4. 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

  1. 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
  2. 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

  1. Document generation

    • API interface documentation:
      • Refer to references/api-doc-template.md template 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.py to validate format correctness
    • Database design documentation:
      • Refer to references/db-doc-template.md template structure
      • Generate table structure list, data dictionary, indexing strategy, relationship diagram
      • Use scripts/validate_sql.py to validate DDL syntax correctness
    • Protocol and communication specifications:
      • Refer to references/protocol-template.md template 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.py to validate .proto file syntax
  2. 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

  1. Format validation

    • Use scripts/validate_openapi.py to validate OpenAPI format
    • Use scripts/validate_protobuf.py to validate Protobuf format
    • Use scripts/validate_sql.py to validate SQL syntax
  2. 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
  3. 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:

  1. Whether the file path is correct
  2. Whether the file format conforms to the specification (YAML/JSON/SQL)
  3. 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:

  1. Compare the documentation differences before and after the change
  2. Analyze the scope of impact (which interfaces/tables/protocols are affected)
  3. 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