Skill: gechengling/api-design-documentation (version 1.0.0)

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


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal:  | SkillSpector: clean (LOW)