AgentSkillsCN

api-documenting

从代码中生成API文档。当用户希望记录API、创建API参考、生成端点文档，或需要OpenAI/Swagger规范方面的帮助时使用。

SKILL.md
--- frontmatter
name: api-documenting
description: Generate API documentation from code. Use When the user wans to document APIs, create API reference, generate endpoint documentation, or needs help with OpenAI/Swagger specs. 
allowed-tools:
  - Read
  - Grep
  - Glob
  - Write

API Documentation Generator

Generate comprehensive API documentation from source code.

Quick Reference

For common documentation patterns, see PATTERNS.md.

Documentation Standards

See STANDARDS.md for our documentation conventions.

Process

Step 1: Identify API Endpoints

Look for:

  • •Route definitions (Express, FastAPI, etc.)
  • •Controller methods
  • •Handler functions

Step 2: Extract Information

For each endpoint, extract:

  • •HTTP method (GET, POST, PUT, DELETE, etc.)
  • •Path/route
  • •Parameters (path, query, body)
  • •Request/response schemas
  • •Authentication requirements

Step3: Generate Documentaion

Use the template in templates/endpoint.md for consistent formatting.

Step4: Create Overview

Generate an index of all endpoints with the template in templates/index.md.

Output Formats

Markdown (Default)

Generate markdown documentation suitable for README or docs site.

OpenAPI/Swagger

If requested, generate OpenAPI 3.0 spec.See templates/openapi.yaml for structure.

Examples

See EXAMPLES.md for sample inputs and outputs.

Scripts

To auto-detect routes in common frameworks:

bash
python scripts/detect_routes.py <source_directory>

To validate generated OpenAPI spec:

bash
./scripts/validate_openapi.sh <spec_file>