AgentSkillsCN

api-documentation-generator

从API路由文件生成OpenAPI/Swagger文档。在处理REST API、Express路由、FastAPI端点或用户请求API文档时使用。

SKILL.md
--- frontmatter
name: api-documentation-generator
description: Generates OpenAPI/Swagger documentation from API route files. Use when working with REST APIs, Express routes, FastAPI endpoints, or when user requests API documentation.
allowed-tools: Read, Grep, Glob, Write, Edit

API Documentation Generator

This skill automatically generates OpenAPI 3.0 (Swagger) documentation from API route files in your codebase.

When to Use This Skill

  • •User asks to generate API documentation
  • •Working with REST API endpoints
  • •Need to create or update OpenAPI/Swagger specs
  • •Setting up API documentation for Express, FastAPI, Flask, NestJS, or similar frameworks

Instructions

1. Discover API Routes

Search the codebase for API route definitions:

  • •Express/Node.js: Look for app.get(), app.post(), router.get(), etc.
  • •FastAPI/Python: Look for @app.get(), @router.post(), decorators
  • •Flask: Look for @app.route() decorators
  • •NestJS: Look for @Get(), @Post(), @Controller() decorators
  • •Rails: Look for routes in config/routes.rb

Use Glob to find route files (e.g., **/*routes*.{js,ts,py}, **/controllers/**/*.{js,ts})

2. Analyze Route Patterns

For each discovered route, extract:

  • •HTTP Method: GET, POST, PUT, PATCH, DELETE
  • •Path: The endpoint URL (e.g., /api/users/:id)
  • •Parameters: Path params, query params, request body
  • •Response: Expected response structure
  • •Authentication: Whether auth is required
  • •Description: Comments or docstrings near the route

3. Generate OpenAPI Specification

Create or update an OpenAPI 3.0 specification file (typically openapi.yaml or swagger.json):

  • •Start with the template from templates/openapi-3.0.yaml
  • •Map each route to an OpenAPI path object
  • •Define request/response schemas using JSON Schema
  • •Include parameter definitions (path, query, body)
  • •Add authentication schemes if detected (Bearer, API Key, OAuth2)
  • •Group endpoints by tags (e.g., "Users", "Products", "Auth")

4. Validate Completeness

Check that the generated documentation includes:

  • •All discovered endpoints
  • •Accurate HTTP methods and paths
  • •Request/response examples where possible
  • •Error responses (400, 401, 404, 500, etc.)
  • •Security requirements

5. Output Location

  • •Save as openapi.yaml in the project root, or
  • •Place in docs/ or api/ directory if those exist
  • •Ask user for preferred location if unclear

Framework-Specific Notes

Express/Node.js

  • •Check for route middleware that might affect auth/validation
  • •Look for request validators (Joi, express-validator, etc.)
  • •Extract JSDoc comments for endpoint descriptions

FastAPI

  • •FastAPI auto-generates OpenAPI docs, but this skill can enhance them
  • •Extract Pydantic models for request/response schemas
  • •Check for response_model and status_code parameters

NestJS

  • •Look for DTOs (Data Transfer Objects) for schemas
  • •Check for Swagger decorators (@ApiOperation, @ApiResponse)
  • •Extract metadata from controller and method decorators

Best Practices

  1. •Use existing schemas: If the codebase has TypeScript interfaces, Pydantic models, or similar, use them for accurate schemas
  2. •Include examples: Add request/response examples from tests if available
  3. •Group logically: Organize endpoints by resource or feature area using tags
  4. •Version appropriately: Use the API version from the codebase (e.g., "1.0.0")
  5. •Add descriptions: Use code comments/docstrings for endpoint descriptions

Supporting Files

  • •templates/openapi-3.0.yaml: Base OpenAPI template
  • •examples.md: Framework-specific examples