Api Design Documentation

Data & APIs

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文档.

Install

openclaw skills install api-design-documentation

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.)
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 <your_token>


### 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

| Standard | Support Level |
|----------|---------------|
| OpenAPI 3.0 | Full |
| OpenAPI 3.1 | Full |
| AsyncAPI 2.0 | Full |
| GraphQL SDL | Full |
| RAML | Read/Convert |
| Swagger 2.0 | Read/Convert |

## 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

Api Design Documentation

Install

API Design & Documentation Generator

Overview

Triggers

Features

1. API Design Intelligence

2. Documentation Generation

3. Mock Server Setup

4. API Quality Assurance

Workflow

API Documentation Workflow

Quick API Spec Generation Workflow

Input Examples

Example 1: API Description to OpenAPI

Example 2: Generate Documentation from OpenAPI

Code Samples

Python

JavaScript

Response

200 OK

400 Bad Request

Examples

Request

Response

Related skills