SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsapi-doc-generator

api-doc-generator

Coding & development

View repository

Updated 10-16 01:19

About this skill

API Documentation Auto-Generator

Task Objective

  • This Skill is used to: automatically extract API information from project code and generate complete API documentation
  • Capabilities include: code scanning, route recognition, module division, document structuring, content filling
  • Trigger conditions: the user requests "generate API documentation", "analyze project API", "write interface documentation", etc.

Prerequisites

Dependency Description

This Skill uses only the Python standard library (ast, re, json, pathlib, etc.) and requires no additional dependencies to be installed.

Non-standard File/Folder Preparation

No prior creation is required; the output directory will be created automatically when the documentation is generated.

Operation Steps

Standard Process

  1. Step 1: Scan Project API

    • Call scripts/api_scanner.py to scan the project code
    • Parameters:
      • --project-dir: Project root directory (required)
      • --framework: Framework type (auto/flask/fastapi/express/django/nestjs/spring/gin/echo/react/vue/angular/svelte/nextjs/nuxtjs, default auto)
      • --output: Output JSON file path (default api_scan_result.json)
    • Output: A JSON file containing information about all API endpoints

  2. Step 2: Module Division and Hierarchy Analysis

    • Call scripts/module_classifier.py to analyze the API structure
    • Parameters:
      • --input: The JSON file path output in the previous step
      • --output: Output JSON file path (default api_modules.json)
    • Output: An API list with module grouping and hierarchy information

  3. Step 3: Generate Document Structure

    • Create the api/ folder in the project root directory
    • According to references/doc-structure.md create the document framework according to the specifications in:
      • api/overview.md - API Overview
      • api/authentication.md - Authentication Method
      • api/base-info.md - Basic Information
      • api/endpoints/ - Endpoint Details (organized by module)
      • api/error-handling.md - Error Handling
      • api/rate-limiting.md - Rate Limiting
      • api/changelog.md - Changelog
      • api/support.md - Support and Feedback

  4. Step 4: Fill in Document Content

    • Call scripts/doc_generator.py to generate the complete documentation
    • Parameters:
      • --input: The JSON file path of the module classification result
      • --output-dir: Output directory (default api/)
    • Output: Complete API documentation

Optional Branches

Backend Framework Branches

  • When the project uses the Flask framework: In Step 1, explicitly specify --framework flask to improve recognition accuracy
  • When the project uses the FastAPI framework: In Step 1, explicitly specify --framework fastapi to leverage type annotation information
  • When the project uses the Express framework: In Step 1, explicitly specify --framework express to recognize JavaScript routes
  • When the project uses the Django framework: In Step 1, explicitly specify --framework django to recognize DRF views
  • When the project uses the NestJS framework: In Step 1, explicitly specify --framework nestjs to identify decorators
  • When the project uses the Spring Boot framework: In step 1, explicitly specify --framework spring to identify annotations
  • When the project uses the Gin framework: In step 1, explicitly specify --framework gin to identify Go routes
  • When the project uses the Echo framework: In step 1, explicitly specify --framework echo to identify Go routes
  • When custom module grouping is needed: After step 2, manually adjust the module grouping logic before generating the documentation

Frontend framework branches

  • When the project uses the React framework: In step 1, explicitly specify --framework react to identify components
  • When the project uses the Vue framework: In step 1, explicitly specify --framework vue to identify components
  • When the project uses the Angular framework: In step 1, explicitly specify --framework angular to identify components
  • When the project uses the Svelte framework: In step 1, explicitly specify --framework svelte to identify components
  • When the project uses the Next.js framework: In step 1, explicitly specify --framework nextjs to identify API routes
  • When the project uses the Nuxt.js framework: In step 1, explicitly specify --framework nuxtjs to identify API routes

Resource index

Required scripts

  • See scripts/api_scanner.py

    • Purpose: Scan project code to extract API routes and parameter information
    • Parameters: --project-dir, --framework, --output
    • Supported frameworks: Flask, FastAPI, Django, Express, NestJS, Spring Boot, Gin, Echo, React, Vue, Angular, Svelte, Next.js, Nuxt.js

  • See scripts/module_classifier.py

    • Purpose: Automatically divide modules and hierarchy structure based on route paths
    • Parameters: --input, --output

  • See scripts/doc_generator.py

    • Purpose: Generate complete documentation based on module classification results
    • Parameters: --input, --output-dir

Domain references

  • See references/doc-structure.md

    • When to read: Refer to this when generating the document structure in step 3
    • Content: Standard chapter structure and format specifications for API documentation

  • See references/framework-patterns.md

    • When to read: Understand how the script identifies route definitions in different frameworks
    • Content: Route definition patterns and identification rules for various web frameworks

  • See references/frontend-frameworks.md

    • When to read: Understand how frontend frameworks organize API documentation
    • Content: Best practices for component identification and documentation generation in frontend frameworks

  • See references/backend-frameworks.md

    • When to read: Understand how backend frameworks organize API documentation
    • Content: Best practices for route identification and documentation generation in backend frameworks

  • See references/api-doc-best-practices.md

    • When to read: Understand general best practices for API documentation
    • Content: Organization suggestions, format specifications, and common issues for API documentation

Output assets

  • See assets/templates/
    • Purpose: Provide documentation templates for each chapter and endpoint
    • Includes: overview-template.md, endpoint-template.md, module-template.md
    • Supports: Backend API documentation and frontend component documentation

Notes

  • The script uses regular expressions and AST parsing to identify routes. For complex dynamic routes, it may not be able to fully identify them, and manual supplementation is required.
  • Parameter extraction depends on code comments and type annotations. It is recommended to improve docstrings in the code.
  • Module division is based on the first segment of the path. For special structures, manual adjustment may be required.
  • After generating the documentation, it is recommended to manually review and supplement business descriptions, usage examples, etc.
  • Read reference documentation only when needed to keep the context concise.
  • For frontend frameworks, component recognition depends on component definition patterns. It is recommended to use standard component definition methods.
  • For backend frameworks, route recognition depends on framework-specific decorators or method calls. It is recommended to use standard route definition methods.
  • The script provides the basic framework and logic. A complete implementation requires further development according to specific needs.

Usage Examples

Example 1: Flask Project Documentation Generation

# 1. 扫描Flask项目
python scripts/api_scanner.py \
  --project-dir /path/to/flask/project \
  --framework flask \
  --output api_scan_result.json

# 2. 划分模块
python scripts/module_classifier.py \
  --input api_scan_result.json \
  --output api_modules.json

# 3. 生成文档
python scripts/doc_generator.py \
  --input api_modules.json \
  --output-dir api/

Example 2: FastAPI Project Documentation Generation

# FastAPI项目会自动识别类型注解和Pydantic模型
python scripts/api_scanner.py \
  --project-dir /path/to/fastapi/project \
  --framework fastapi

python scripts/module_classifier.py \
  --input api_scan_result.json

python scripts/doc_generator.py \
  --input api_modules.json \
  --output-dir api/

Example 3: Express Project Documentation Generation

# Node.js Express项目
python scripts/api_scanner.py \
  --project-dir /path/to/express/project \
  --framework express

python scripts/module_classifier.py \
  --input api_scan_result.json

python scripts/doc_generator.py \
  --input api_modules.json \
  --output-dir api/

Example 4: React Project Component Documentation Generation

# React项目组件文档生成
python scripts/api_scanner.py \
  --project-dir /path/to/react/project \
  --framework react

python scripts/module_classifier.py \
  --input api_scan_result.json

python scripts/doc_generator.py \
  --input api_modules.json \
  --output-dir components/

Example 5: Vue Project Component Documentation Generation

# Vue项目组件文档生成
python scripts/api_scanner.py \
  --project-dir /path/to/vue/project \
  --framework vue

python scripts/module_classifier.py \
  --input api_scan_result.json

python scripts/doc_generator.py \
  --input api_modules.json \
  --output-dir components/

Example 6: Next.js Project API Documentation Generation

# Next.js项目API路由文档生成
python scripts/api_scanner.py \
  --project-dir /path/to/nextjs/project \
  --framework nextjs

python scripts/module_classifier.py \
  --input api_scan_result.json

python scripts/doc_generator.py \
  --input api_modules.json \
  --output-dir api/

Example 7: Nuxt.js Project API Documentation Generation

# Nuxt.js项目API路由文档生成
python scripts/api_scanner.py \
  --project-dir /path/to/nuxtjs/project \
  --framework nuxtjs

python scripts/module_classifier.py \
  --input api_scan_result.json

python scripts/doc_generator.py \
  --input api_modules.json \
  --output-dir api/

Example 8: Django Project Documentation Generation

# Django REST Framework项目文档生成
python scripts/api_scanner.py \
  --project-dir /path/to/django/project \
  --framework django

python scripts/module_classifier.py \
  --input api_scan_result.json

python scripts/doc_generator.py \
  --input api_modules.json \
  --output-dir api/

Example 9: NestJS Project Documentation Generation

# NestJS项目文档生成
python scripts/api_scanner.py \
  --project-dir /path/to/nestjs/project \
  --framework nestjs

python scripts/module_classifier.py \
  --input api_scan_result.json

python scripts/doc_generator.py \
  --input api_modules.json \
  --output-dir api/

Example 10: Spring Boot Project Documentation Generation

# Spring Boot项目文档生成
python scripts/api_scanner.py \
  --project-dir /path/to/spring/project \
  --framework spring

python scripts/module_classifier.py \
  --input api_scan_result.json

python scripts/doc_generator.py \
  --input api_modules.json \
  --output-dir api/

Example 11: Gin Project Documentation Generation

# Gin项目文档生成
python scripts/api_scanner.py \
  --project-dir /path/to/gin/project \
  --framework gin

python scripts/module_classifier.py \
  --input api_scan_result.json

python scripts/doc_generator.py \
  --input api_modules.json \
  --output-dir api/

Example 12: Echo Project Documentation Generation

# Echo项目文档生成
python scripts/api_scanner.py \
  --project-dir /path/to/echo/project \
  --framework echo

python scripts/module_classifier.py \
  --input api_scan_result.json

python scripts/doc_generator.py \
  --input api_modules.json \
  --output-dir api/

Example 13: Automatic Framework Detection

# 自动检测项目框架
python scripts/api_scanner.py \
  --project-dir /path/to/project \
  --framework auto

python scripts/module_classifier.py \
  --input api_scan_result.json

python scripts/doc_generator.py \
  --input api_modules.json \
  --output-dir api/

Supported Frameworks

Frontend Frameworks

  • React
  • Vue
  • Angular
  • Svelte
  • Next.js
  • Nuxt.js

Backend Frameworks

  • Flask
  • FastAPI
  • Django
  • Express
  • NestJS
  • Spring Boot
  • Gin
  • Echo

Framework Recognition Rules

Backend Framework Detection Priority

  1. Detect from fastapi import or FastAPI( → FastAPI
  2. Detect from flask import or Flask( → Flask
  3. Detect from django.urls import or from rest_framework import → Django
  4. Detect @Controller or @RestController → Spring Boot
  5. Detect @nestjs/common → NestJS
  6. Detect github.com/gin-gonic/gin → Gin
  7. Detect github.com/labstack/echo/v4 → Echo
  8. Detect require('express') or express() → Express

Frontend Framework Detection Priority

  1. Detect import React or from 'react' → React
  2. Detect <template> tag or defineProps → Vue
  3. Detect @Component or @angular/core → Angular
  4. Detect <script> tag and no lang="ts" → Svelte
  5. Detect next/server or pages/api/ → Next.js
  6. Detect defineEventHandler or server/api/ → Nuxt.js

Documentation Generation Best Practices

  1. Code Comments: Add clear docstrings and comments in the code
  2. Type Annotations: Use type annotations (TypeScript, FastAPI, NestJS)
  3. Standard Naming: Use standard naming conventions and code structure
  4. Manual Review: Manually review and supplement after generating documentation
  5. Regular Updates: Regularly update documentation to keep it in sync with the code

Frequently Asked Questions

Q1: How can I improve route recognition accuracy?

A: Explicitly specify the framework type in step 1, using the --framework parameter.

Q2: How can I customize module grouping?

A: After step 2, manually adjust the module grouping logic before generating the documentation.

Q3: How should complex dynamic routes be handled?

A: For complex dynamic routing, it may not be possible to fully identify it, and documentation information needs to be supplemented manually.

Q4: How to handle frontend component documentation?

A: Use the --framework react/vue/angular/svelte parameter, and the script will identify component definitions and generate component documentation.

Q5: How to handle Next.js/Nuxt.js API routes?

A: Use the --framework nextjs/nuxtjs parameter, and the script will identify API routes and generate API documentation.

Q6: Is the script fully implemented?

A: The script provides a basic framework and logic; a complete implementation requires further development based on specific needs.

Future optimization

  1. Improve the script implementation and add more features
  2. Optimize the recognition algorithm to improve accuracy
  3. Add documentation quality check functionality
  4. Support multiple documentation output formats (such as HTML, PDF)
  5. Integrate CI/CD to automatically generate and update documentation