\r \r

API Design & Documentation Generator\r

\r

Overview\r

\r 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.\r \r

Triggers\r

\r

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

Features\r

\r

1. API Design Intelligence\r

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

2. Documentation Generation\r

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

3. Mock Server Setup\r

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

4. API Quality Assurance\r

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

Workflow\r

\r

API Documentation Workflow\r

\r

1. INPUT: API description or existing code\r
   ↓\r
2. DESIGN: Generate OpenAPI specification\r
   - Define endpoints\r
   - Schema definitions\r
   - Authentication/authorization\r
   - Error responses\r
   ↓\r
3. VALIDATE: Check design quality\r
   - REST best practices\r
   - Security considerations\r
   - Completeness check\r
   ↓\r
4. DOCUMENT: Generate comprehensive docs\r
   - Reference documentation\r
   - Quick-start guides\r
   - Code samples\r
   - Tutorials\r
   ↓\r
5. TEST: Create mock server + test cases\r
```\r
\r
### Quick API Spec Generation Workflow\r
\r
```\r
Step 1: Describe your API\r
├── What does it do?\r
├── Who uses it?\r
└── What data does it manage?\r
\r
Step 2: Define endpoints\r
├── Resources (nouns, not verbs)\r
├── CRUD operations\r
└── Query parameters\r
\r
Step 3: Specify data models\r
├── Request/response schemas\r
├── Validation rules\r
└── Error formats\r
\r
Step 4: Add security\r
├── Authentication method\r
├── Authorization scopes\r
└── Rate limiting\r
\r
Step 5: Generate artifacts\r
├── OpenAPI spec (YAML/JSON)\r
├── Documentation\r
└── Code samples\r
```\r
\r
## Input Examples\r
\r
### Example 1: API Description to OpenAPI\r
\r
**Input:**\r
```\r
Design a REST API for a task management system.\r
- Users can create, read, update, delete tasks\r
- Tasks have: title, description, due_date, priority, status, tags\r
- Support pagination for listing tasks\r
- Require JWT authentication\r
```\r
\r
**Expected Output (OpenAPI 3.0):**\r
```yaml\r
openapi: 3.0.3\r
info:\r
  title: Task Management API\r
  version: 1.0.0\r
  description: API for managing tasks with full CRUD operations\r
\r
paths:\r
  /tasks:\r
    get:\r
      summary: List all tasks\r
      parameters:\r
        - name: page\r
          in: query\r
          schema:\r
            type: integer\r
            default: 1\r
        - name: limit\r
          in: query\r
          schema:\r
            type: integer\r
            default: 20\r
      responses:\r
        '200':\r
          description: List of tasks\r
          content:\r
            application/json:\r
              schema:\r
                type: object\r
                properties:\r
                  data:\r
                    type: array\r
                    items:\r
                      $ref: '#/components/schemas/Task'\r
                  pagination:\r
                    $ref: '#/components/schemas/Pagination'\r
    post:\r
      summary: Create a new task\r
      requestBody:\r
        required: true\r
        content:\r
          application/json:\r
            schema:\r
              type: object\r
              required: [title]\r
              properties:\r
                title:\r
                  type: string\r
                description:\r
                  type: string\r
                due_date:\r
                  type: string\r
                  format: date\r
                priority:\r
                  type: string\r
                  enum: [low, medium, high]\r
      responses:\r
        '201':\r
          description: Task created\r
\r
  /tasks/{id}:\r
    get:\r
      summary: Get a task by ID\r
      parameters:\r
        - name: id\r
          in: path\r
          required: true\r
          schema:\r
            type: string\r
      responses:\r
        '200':\r
          description: Task details\r
        '404':\r
          description: Task not found\r
\r
components:\r
  schemas:\r
    Task:\r
      type: object\r
      properties:\r
        id:\r
          type: string\r
        title:\r
          type: string\r
        description:\r
          type: string\r
        due_date:\r
          type: string\r
          format: date\r
        priority:\r
          type: string\r
        status:\r
          type: string\r
        tags:\r
          type: array\r
          items:\r
            type: string\r
    Pagination:\r
      type: object\r
      properties:\r
        page:\r
          type: integer\r
        limit:\r
          type: integer\r
        total:\r
          type: integer\r
  securitySchemes:\r
    BearerAuth:\r
      type: http\r
      scheme: bearer\r
      bearerFormat: JWT\r
```\r
\r
### Example 2: Generate Documentation from OpenAPI\r
\r
**Input:** OpenAPI spec (above YAML)\r
\r
**Expected Output Sections:**\r
```markdown\r
# Task Management API Documentation\r
\r
## Getting Started\r
\r
### Authentication\r
All endpoints require a valid JWT token in the Authorization header:\r
```\r
Authorization: Bearer \x3Cyour_token>\r
```\r
\r
### Base URL\r
```\r
Production: https://api.tasks.example.com/v1\r
```\r
\r
## Endpoints\r
\r
### List Tasks\r
Retrieves a paginated list of all tasks.\r
\r
**Request**\r
```bash\r
curl -X GET "https://api.tasks.example.com/v1/tasks?page=1&limit=20" \\r
  -H "Authorization: Bearer \x3Ctoken>"\r
```\r
\r
**Response**\r
```json\r
{\r
  "data": [\r
    {\r
      "id": "task_123",\r
      "title": "Complete API docs",\r
      "priority": "high",\r
      "status": "pending"\r
    }\r
  ],\r
  "pagination": {\r
    "page": 1,\r
    "limit": 20,\r
    "total": 45\r
  }\r
}\r
```\r
\r
## Code Samples\r
\r
### Python\r
```python\r
import requests\r
\r
response = requests.get(\r
    "https://api.tasks.example.com/v1/tasks",\r
    headers={"Authorization": "Bearer \x3Ctoken>"}\r
)\r
tasks = response.json()\r
```\r
\r
### JavaScript\r
```javascript\r
const response = await fetch(\r
  'https://api.tasks.example.com/v1/tasks',\r
  {\r
    headers: { 'Authorization': 'Bearer \x3Ctoken>' }\r
  }\r
);\r
const { data: tasks } = await response.json();\r
```\r
```\r
\r
### Example 3: Code Sample Generation\r
\r
**Input:** OpenAPI endpoint definition + language (Python)\r
\r
**Output:** Complete, runnable code snippet with error handling\r
\r
## Output Templates\r
\r
### Template: API Reference Page\r
```markdown\r
# {Endpoint Name}\r
\r
{Method} {Path}\r
\r
## Description\r
{What this endpoint does}\r
\r
## Authentication\r
{Authentication requirements}\r
\r
## Request}\r
\r
### Path Parameters\r
| Name | Type | Required | Description |\r
|------|------|----------|-------------|\r
| ... | ... | ... | ... |\r
\r
### Query Parameters\r
| Name | Type | Required | Default | Description |\r
|------|------|----------|---------|-------------|\r
| ... | ... | ... | ... | ... |\r
\r
### Request Body\r
```json\r
{Request body schema}\r
```\r
\r
## Response\r
\r
### 200 OK\r
```json\r
{Response schema}\r
```\r
\r
### 400 Bad Request\r
```json\r
{\r
  "error": {\r
    "code": "VALIDATION_ERROR",\r
    "message": "Description of the error",\r
    "details": [...]\r
  }\r
}\r
```\r
\r
## Examples\r
\r
### Request\r
```bash\r
curl -X {METHOD} {URL} \\r
  -H "Content-Type: application/json" \\r
  -H "Authorization: Bearer \x3Ctoken>" \\r
  -d '{body}'\r
```\r
\r
### Response\r
```json\r
{response example}\r
```\r
```\r
\r
## Best Practices\r
\r
### For API Design\r
1. **Use nouns for resources:** `/users` not `/getUsers`\r
2. **Plural naming:** `/tasks` not `/task`\r
3. **Nest related resources:** `/users/{id}/tasks`\r
4. **Version from day one:** `/v1`, `/v2`\r
5. **Use appropriate HTTP methods:** GET (read), POST (create), PUT (replace), PATCH (update), DELETE (remove)\r
6. **Return proper status codes:** 200, 201, 400, 401, 403, 404, 500\r
\r
### For Documentation\r
1. **Start with getting started:** Don't assume users know your API\r
2. **Provide runnable examples:** Copy-paste ready code beats prose\r
3. **Document errors clearly:** Users will hit them\r
4. **Keep it updated:** Outdated docs are worse than no docs\r
5. **Include changelog:** Help users track changes\r
\r
### For Security\r
1. **Never log sensitive data:** Tokens, passwords, PII\r
2. **Use HTTPS only:** No exceptions\r
3. **Implement rate limiting:** Protect your infrastructure\r
4. **Validate all input:** Never trust client data\r
\r
## Supported Standards\r
\r
| Standard | Support Level |\r
|----------|---------------|\r
| OpenAPI 3.0 | Full |\r
| OpenAPI 3.1 | Full |\r
| AsyncAPI 2.0 | Full |\r
| GraphQL SDL | Full |\r
| RAML | Read/Convert |\r
| Swagger 2.0 | Read/Convert |\r
\r
## Supported Languages for Code Generation\r
\r
- Python (requests, httpx)\r
- JavaScript (fetch, axios)\r
- TypeScript\r
- Go (net/http, gorilla)\r
- Java (HttpClient, OkHttp)\r
- C# (.NET HttpClient)\r
- Ruby (Net::HTTP)\r
- PHP (cURL)\r
- curl\r
- Kotlin\r
\r
## Version History\r
\r
- **1.0.0** (2026-05-15): Initial release\r
  - OpenAPI 3.0/3.1 generation\r
  - Multi-language code samples\r
  - Documentation generation\r
  - Basic validation\r