back
loading skill details...
AI-powered API design and documentation assistant — generate RESTful/OpenAPI specs, write comprehensive API docs (guides, tutorials, reference), create mock...
---
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.)
- 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):**
```yaml
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:**
```markdown
# 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**
```json
{
"data": [
{
"id": "task_123",
"title": "Complete API docs",
"priority": "high",
"status": "pending"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 45
}
}
```
## Code Samples
### Python
```python
import requests
response = requests.get(
"https://api.tasks.example.com/v1/tasks",
headers={"Authorization": "Bearer <token>"}
)
tasks = response.json()
```
### JavaScript
```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
```json
{Response schema}
```
### 400 Bad Request
```json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Description of the error",
"details": [...]
}
}
```
## Examples
### Request
```bash
curl -X {METHOD} {URL} \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{body}'
```
### Response
```json
{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
don't have the plugin yet? install it then click "run inline in claude" again.