name: "API Design & Documentation Generator" description: "AI-powered API design and documentation assistant — generate RESTful/OpenAPI specs, write comprehensive API docs (guides, tutorials, reference), create mock servers, validate API designs, and produce SDK code snippets. Supports OpenAPI 3.0/3.1, AsyncAPI, GraphQL SDL, and major languages. Built for backend developers, API product managers, DevOps engineers, and technical writers who need to design, document, and ship APIs faster. Keywords: API documentation, OpenAPI spec, REST API design, API reference, developer portal, API guide, Swagger, AsyncAPI, GraphQL schema, API validation, mock server, SDK generation, API设计, 接口文档, OpenAPI, Swagger文档." version: "1.0.0"

API Design & Documentation Generator

Overview

Stop wrestling with API documentation. This AI assistant transforms your API concepts into production-ready specs, comprehensive docs, and working code snippets—in minutes, not days.

Triggers

• 中文触发词：API文档、接口文档、生成OpenAPI、API设计、Swagger文档、接口规范、API教程、GraphQL文档
• English triggers: API documentation, OpenAPI spec, REST API design, Swagger docs, API reference, generate API docs, API guide, mock server

Features

1. API Design Intelligence

• Generate OpenAPI 3.0/3.1 specs from descriptions or existing code
• Validate API designs against best practices (REST maturity, naming conventions)
• Suggest improvements for security, performance, and developer experience
• Convert between OpenAPI, AsyncAPI, and GraphQL SDL

2. Documentation Generation

• Write comprehensive API reference documentation
• Create getting-started guides and tutorials
• Generate authentication and authorization guides
• Produce code samples in 10+ languages (Python, JavaScript, TypeScript, Go, Java, C#, Ruby, PHP, curl, etc.)

  7w4.net收录了海量优质技能插件。

• Create Postman collections and Insomnia specifications

3. Mock Server Setup

• Generate mock server code from OpenAPI specs
• Support for static and dynamic mocking
• Create sample request/response pairs
• Set up delay rules for realistic testing

4. API Quality Assurance

• Validate OpenAPI/AsyncAPI syntax
• Check for common anti-patterns
• Ensure backward compatibility
• Generate changelog drafts for API updates

Workflow

API Documentation Workflow

1. INPUT: API description or existing code
   ↓
2. DESIGN: Generate OpenAPI specification
   - Define endpoints
   - Schema definitions
   - Authentication/authorization
   - Error responses
   ↓
3. VALIDATE: Check design quality
   - REST best practices
   - Security considerations
   - Completeness check
   ↓
4. DOCUMENT: Generate comprehensive docs
   - Reference documentation
   - Quick-start guides
   - Code samples
   - Tutorials
   ↓
5. TEST: Create mock server + test cases

Quick API Spec Generation Workflow

Step 1: Describe your API
├── What does it do?
├── Who uses it?
└── What data does it manage?

Step 2: Define endpoints
├── Resources (nouns, not verbs)
├── CRUD operations
└── Query parameters

Step 3: Specify data models
├── Request/response schemas
├── Validation rules
└── Error formats

Step 4: Add security
├── Authentication method
├── Authorization scopes
└── Rate limiting

Step 5: Generate artifacts
├── OpenAPI spec (YAML/JSON)
├── Documentation
└── Code samples

Input Examples

Example 1: API Description to OpenAPI

Input:

Design a REST API for a task management system.
- Users can create, read, update, delete tasks
- Tasks have: title, description, due_date, priority, status, tags
- Support pagination for listing tasks
- Require JWT authentication

Expected Output (OpenAPI 3.0):

openapi: 3.0.3
info:
  title: Task Management API
  version: 1.0.0
  description: API for managing tasks with full CRUD operations

paths:
  /tasks:
    get:
      summary: List all tasks
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: List of tasks
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
    post:
      summary: Create a new task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title]
              properties:
                title:
                  type: string
                description:
                  type: string
                due_date:
                  type: string
                  format: date
                priority:
                  type: string
                  enum: [low, medium, high]
      responses:
        '201':
          description: Task created

  /tasks/{id}:
    get:
      summary: Get a task by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Task details
        '404':
          description: Task not found

components:
  schemas:
    Task:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
        due_date:
          type: string
          format: date
        priority:
          type: string
        status:
          type: string
        tags:
          type: array
          items:
            type: string
    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

Example 2: Generate Documentation from OpenAPI

Input: OpenAPI spec (above YAML)

Expected Output Sections:

# Task Management API Documentation

## Getting Started

### Authentication
All endpoints require a valid JWT token in the Authorization header:

Authorization: Bearer

### Base URL

Production: https://api.tasks.example.com/v1

## Endpoints

### List Tasks
Retrieves a paginated list of all tasks.

**Request**
```bash
curl -X GET "https://api.tasks.example.com/v1/tasks?page=1&limit=20" \
  -H "Authorization: Bearer <token>"

Response

{
  "data": [
    {
      "id": "task_123",
      "title": "Complete API docs",
      "priority": "high",
      "status": "pending"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45
  }
}

Code Samples

Python

import requests

response = requests.get(
    "https://api.tasks.example.com/v1/tasks",
    headers={"Authorization": "Bearer <token>"}
)
tasks = response.json()

JavaScript

const response = await fetch(
  'https://api.tasks.example.com/v1/tasks',
  {
    headers: { 'Authorization': 'Bearer <token>' }
  }
);
const { data: tasks } = await response.json();

### Example 3: Code Sample Generation

**Input:** OpenAPI endpoint definition + language (Python)

**Output:** Complete, runnable code snippet with error handling

## Output Templates

### Template: API Reference Page
```markdown
# {Endpoint Name}

{Method} {Path}

## Description
{What this endpoint does}

## Authentication
{Authentication requirements}

## Request}

### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| ... | ... | ... | ... |

### Query Parameters
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| ... | ... | ... | ... | ... |

### Request Body
```json
{Request body schema}

Response

200 OK

{Response schema}

400 Bad Request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Description of the error",
    "details": [...]
  }
}

Examples

Request

curl -X {METHOD} {URL} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{body}'

Response

{response example}

```

Best Practices

For API Design

1. Use nouns for resources: /users not /getUsers
2. Plural naming: /tasks not /task
3. Nest related resources: /users/{id}/tasks
4. Version from day one: /v1, /v2
5. Use appropriate HTTP methods: GET (read), POST (create), PUT (replace), PATCH (update), DELETE (remove)
6. Return proper status codes: 200, 201, 400, 401, 403, 404, 500

For Documentation

1. Start with getting started: Don't assume users know your API
2. Provide runnable examples: Copy-paste ready code beats prose
3. Document errors clearly: Users will hit them
4. Keep it updated: Outdated docs are worse than no docs
5. Include changelog: Help users track changes

For Security

1. Never log sensitive data: Tokens, passwords, PII
2. Use HTTPS only: No exceptions
3. Implement rate limiting: Protect your infrastructure
4. Validate all input: Never trust client data

Supported Standards

Supported Languages for Code Generation

• Python (requests, httpx)
• JavaScript (fetch, axios)
• TypeScript
• Go (net/http, gorilla)
• Java (HttpClient, OkHttp)
• C# (.NET HttpClient)
• Ruby (Net::HTTP)
• PHP (cURL)
• curl
• Kotlin

Version History

• 1.0.0 (2026-05-15): Initial release
• OpenAPI 3.0/3.1 generation
• Multi-language code samples
• Documentation generation
• Basic validation

这个 Skill 质量不错，功能覆盖面广，文档写得清楚明白，示例也很丰富，对于需要生成 API 文档或学习 API 设计的开发者很有帮助。优点是支持多种格式和编程语言，工作流程清晰；不足之处在于没有提供可直接使用的代码工具，效果主要依赖 AI 的理解能力，可能不如预期精准。