Update openapi.yaml

Improve: Clean up API description for better readability

openapi.yaml

@@ -2,186 +2,98 @@ openapi: 3.0.3
 info:
   title: XUI.ONE Admin API
   description: |
-    # XUI.ONE Admin API Documentation
+    **Comprehensive API documentation for XUI.ONE IPTV Panel Administration**
     
-    Comprehensive API documentation for XUI.ONE IPTV Panel Administration.
+    ### 🎯 Quick Start
     
-    ## Overview
+    This API provides programmatic access to manage your IPTV platform with 180+ endpoints for:
+    - 📺 Manage subscriptions (Lines, MAG, Enigma2 devices)
+    - 🎬 Control streams, channels, movies, and series  
+    - 📊 Monitor connections and activity logs
+    - ⚙️ Configure servers and load balancers
     
-    The XUI.ONE Admin API provides programmatic access to manage your IPTV platform. With over 180+ endpoints, you can:
+    ---
     
-    - Manage subscriptions (Lines, MAG devices, Enigma2 devices)
+    ### 🔗 Base URL Pattern
-    - Control streams, channels, movies, and series
-    - Monitor connections and logs
-    - Configure servers and load balancers
-    - Administer users and resellers
-    
-    ## Base URL Structure
-    
-    All API requests follow this pattern:
     
     ```
-    http://YOUR_SERVER:PORT/<Access-Code>/?api_key=<API-KEY>&action=ACTION_NAME
+    http://YOUR_SERVER/<Access-Code>/?api_key=<API-KEY>&action=ACTION
     ```
     
-    **Components:**
+    **Replace:**
-    - `YOUR_SERVER` - Your XUI.ONE server IP or domain
+    - `YOUR_SERVER` → Your server domain/IP
-    - `PORT` - API port (default: 80 for HTTP, 8000 for HTTP explicit, 9000 for HTTPS)
+    - `<Access-Code>` → Your access code (e.g., `cSbuFLhp`)
-    - `<Access-Code>` - Unique access code for API access
+    - `<API-KEY>` → Your API key
-    - `<API-KEY>` - Your generated API key
+    - `ACTION` → API action name (e.g., `get_lines`)
-    - `ACTION_NAME` - The API action to perform
     
-    ## Authentication
+    ---
     
-    XUI.ONE API uses **API Key authentication** combined with **Access Codes** for secure access.
+    ### 🔐 Authentication Setup
     
-    ### Prerequisites
+    **Required:**
+    1. XUI.ONE panel installed (v1.5.5+)
+    2. Admin API access code created
+    3. API key generated from profile
     
-    Before using the API, you need:
+    **Quick Setup:**
+    1. Panel → Management → Access Control → Access Codes
+    2. Create "Admin API" access code
+    3. Profile → Generate API Key
+    4. Test: `curl "http://your-server.com/<Access-Code>/?api_key=<API-KEY>&action=user_info"`
     
-    1. ✅ XUI.ONE panel installed and running
+    📖 **[View detailed setup guide →](https://github.com/worldofiptvcom/xui-one-api-docs/blob/main/docs/getting-started.md)**
-    2. ✅ Admin account with appropriate permissions
-    3. ✅ Admin API access code created
-    4. ✅ API key generated
     
-    ### Step 1: Create Admin API Access Code
+    ---
     
-    1. Log into your XUI.ONE admin panel
+    ### 📝 Request Methods
-    2. Navigate to **Management → Access Control → Access Codes**
-    3. Click **Add Access Code**
-    4. Select **Access Type: Admin API**
-    5. Assign to **Administrators** group
-    6. (Optional) Restrict to specific IP address for security
-    7. Save the access code (e.g., `cSbuFLhp`)
     
-    ### Step 2: Generate API Key
+    **GET** - Query data
-    
+    ```
-    1. Log into admin panel
+    /?api_key=<API-KEY>&action=get_lines
-    2. Click your profile (top right)
-    3. Select **Edit Profile**
-    4. Click the blue **Generate API Key** button
-    5. Copy and save your API key (e.g., `8D3135D30437F86EAE2FA4A2A8345000`)
-    
-    ⚠️ **Security Warning:** Keep your API key secure. If compromised, regenerate immediately.
-    
-    ### Step 3: Test Authentication
-    
-    Test your credentials with a simple API call:
-    
-    ```bash
-    curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=user_info"
     ```
     
-    Successful response:
+    **POST** - Create/update data  
+    ```
+    curl -X POST ".../?api_key=<API-KEY>&action=create_line" -d "username=test"
+    ```
+    
+    ---
+    
+    ### ✅ Response Format
+    
+    **Success:**
     ```json
     {
       "status": "STATUS_SUCCESS",
-      "data": {
+      "data": { ... }
-        "username": "admin",
-        "member_group_id": "1",
-        ...
-      }
     }
     ```
     
-    ## Request Methods
+    **Error:**
-    
-    The API supports both **GET** and **POST** methods:
-    
-    ### GET Requests
-    
-    Pass parameters in the URL query string:
-    
-    ```
-    http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=get_lines&limit=10
-    ```
-    
-    ### POST Requests
-    
-    Send parameters as form data or JSON in request body:
-    
-    ```bash
-    curl -X POST "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=create_line" \
-      -d "username=testuser" \
-      -d "password=testpass" \
-      -d "max_connections=1"
-    ```
-    
-    ## Response Format
-    
-    All API responses return JSON with a consistent structure:
-    
-    ### Success Response
-    
-    ```json
-    {
-      "status": "STATUS_SUCCESS",
-      "data": {
-        // Response data here
-      }
-    }
-    ```
-    
-    ### Error Response
-    
     ```json
     {
       "status": "STATUS_FAILURE",
-      "error": "Error message description"
+      "error": "Error description"
     }
     ```
     
-    ## Common Error Messages
+    ---
     
-    | Error Message | Cause | Solution |
+    ### 🔒 Security Best Practices
-    |--------------|-------|----------|
-    | `Invalid API key` | Wrong or expired API key | Regenerate API key in admin profile |
-    | `Access denied` | Invalid access code | Verify access code is correct |
-    | `Missing required parameters` | Required field not provided | Check API documentation for required fields |
-    | `Invalid action` | Action name is incorrect | Verify action name spelling |
-    | `Permission denied` | Insufficient privileges | Ensure API access code is assigned to Administrators group |
     
-    ## Rate Limiting
+    - ✅ Use HTTPS (port 9000) in production
+    - ✅ Whitelist IPs in access code settings
+    - ✅ Rotate API keys regularly
+    - ✅ Never commit keys to version control
     
-    XUI.ONE implements rate limiting to prevent abuse:
+    ---
     
-    - Default: No strict rate limit
+    ### 📚 Resources
-    - Recommended: Max 100 requests per minute per IP
-    - Heavy operations (database queries): Use sparingly
     
-    If you experience rate limiting, implement exponential backoff in your application.
+    - **GitHub:** [Documentation Repository](https://github.com/worldofiptvcom/xui-one-api-docs)
-    
+    - **Community:** [World of IPTV Forums](https://www.worldofiptv.com)
-    ## Security Best Practices
+    - **Getting Started:** [Setup Guide](https://github.com/worldofiptvcom/xui-one-api-docs/blob/main/docs/getting-started.md)
-    
+    - **XUI.ONE:** [Official Website](https://xui.one)
-    1. 🔒 **Use HTTPS** - Always use port 9000 with SSL enabled in production
-    2. 🔐 **IP Whitelisting** - Restrict API access to specific IPs
-    3. 🔑 **Rotate Keys** - Regenerate API keys periodically
-    4. 📝 **Audit Logs** - Monitor API usage via activity logs
-    5. 🚫 **Never Expose Keys** - Don't commit API keys to version control
-    6. 🛡️ **HMAC Authentication** - Use HMAC for enhanced security (advanced)
-    
-    ## HMAC Authentication (Advanced)
-    
-    For enhanced security, XUI.ONE supports HMAC-based authentication:
-    
-    1. Generate HMAC key: `action=create_hmac`
-    2. Sign each request with HMAC-SHA256
-    3. Include signature in request header
-    
-    See detailed HMAC documentation for implementation details.
-    
-    ## Getting Help
-    
-    - 📖 Documentation: https://github.com/worldofiptvcom/xui-one-api-docs
-    - 💬 Community: World of IPTV Forums (https://www.worldofiptv.com)
-    - 🐛 Issues: Report bugs via GitHub Issues
-    - 📧 Support: Contact XUI.ONE support team
-    
-    ## API Version
-    
-    Current API Version: **v1.5.13**
-    
-    Compatible with XUI.ONE versions 1.5.5+
     
   version: 1.5.13
   contact:
@@ -259,9 +171,14 @@ paths:
       description: |
         Base endpoint for all API requests. All actions are performed by adding the `action` parameter.
         
-        **Usage:**
+        **Usage Pattern:**
         ```
-        /?api_key=<API-KEY>&action=ACTION_NAME&param1=value1&param2=value2
+        /?api_key=<API-KEY>&action=ACTION_NAME&param1=value1
+        ```
+        
+        **Example:**
+        ```bash
+        curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=user_info"
         ```
       operationId: apiBase
       tags:
@@ -289,7 +206,9 @@ paths:
       description: |
         Retrieves information about the currently authenticated admin user.
         
-        **Use Case:** Verify authentication and check admin privileges.
+        **Purpose:** Verify API authentication and check admin privileges.
+        
+        ---
         
         **Example Request:**
         ```bash
@@ -311,6 +230,14 @@ paths:
           }
         }
         ```
+        
+        ---
+        
+        **Use Cases:**
+        - ✅ Test API authentication
+        - ✅ Verify admin access
+        - ✅ Get current user details
+        - ✅ Check account status
       operationId: getUserInfo
       tags:
         - Authentication
@@ -319,13 +246,14 @@ paths:
         - name: action
           in: query
           required: true
+          description: Action to perform
           schema:
             type: string
             enum: [user_info]
           example: user_info
       responses:
         '200':
-          description: Current user information
+          description: Current user information retrieved successfully
           content:
             application/json:
               schema:
@@ -355,7 +283,7 @@ components:
       in: query
       name: api_key
       description: |
-        API key for authentication. Generate from your admin profile in the XUI.ONE panel.
+        API key for authentication. Generate from your admin profile.
         
         **Example:** `8D3135D30437F86EAE2FA4A2A8345000`
 
@@ -415,6 +343,7 @@ components:
 
     UserInfo:
       type: object
+      description: User information object
       properties:
         id:
           type: string