From 1dc6b59c39f0dba21edb4810e66fe2133b69f6b7 Mon Sep 17 00:00:00 2001
From: Lloyd <lloyd@rightup.co.uk>
Date: Thu, 18 Dec 2025 12:54:48 +0000
Subject: [PATCH] Enhance API documentation: rename packet history endpoint,
 improve ACL info response structure, and update descriptions for clarity

---
 repeater/web/html/swagger-ui.html | 25 ++++----
 repeater/web/openapi.yaml         | 96 ++++++++++++++++++-------------
 2 files changed, 68 insertions(+), 53 deletions(-)

diff --git a/repeater/web/html/swagger-ui.html b/repeater/web/html/swagger-ui.html
index d04cd4b..b556315 100644
--- a/repeater/web/html/swagger-ui.html
+++ b/repeater/web/html/swagger-ui.html
@@ -187,20 +187,17 @@
                 showCommonExtensions: true,
                 tagsSorter: "alpha",
                 operationsSorter: "alpha",
-                // Override servers after spec loads
-                onComplete: function() {
-                    // Update the servers in the loaded spec
-                    ui.specActions.updateSpec(
-                        JSON.stringify({
-                            ...ui.specSelectors.specJson().toJS(),
-                            servers: [
-                                {
-                                    url: currentUrl,
-                                    description: "Current host (" + window.location.host + ")"
-                                }
-                            ]
-                        })
-                    );
+                // Intercept requests to use current host
+                requestInterceptor: function(request) {
+                    // Only modify API requests, not the openapi spec fetch
+                    if (!request.url.includes('/api/openapi')) {
+                        // Replace any localhost or hardcoded host with current host
+                        const url = new URL(request.url);
+                        url.protocol = window.location.protocol;
+                        url.host = window.location.host;
+                        request.url = url.toString();
+                    }
+                    return request;
                 }
             });
             
diff --git a/repeater/web/openapi.yaml b/repeater/web/openapi.yaml
index 8b063c8..5a3d3fa 100644
--- a/repeater/web/openapi.yaml
+++ b/repeater/web/openapi.yaml
@@ -209,10 +209,10 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
 
-  /packet_history:
+  /recent_packets:
     get:
       tags: [Packets]
-      summary: Get packet history
+      summary: Get recent packets
       description: Retrieve recent packet history
       parameters:
         - name: limit
@@ -225,7 +225,7 @@ paths:
           description: Maximum number of packets to return
       responses:
         '200':
-          description: Packet history
+          description: Recent packets
           content:
             application/json:
               schema:
@@ -257,25 +257,11 @@ paths:
     get:
       tags: [Charts]
       summary: Get RRD time-series data
-      description: Retrieve Round-Robin Database metrics for graphing
-      parameters:
-        - name: start_time
-          in: query
-          schema:
-            type: integer
-          description: Start timestamp (Unix epoch)
-        - name: end_time
-          in: query
-          schema:
-            type: integer
-          description: End timestamp (Unix epoch)
-        - name: resolution
-          in: query
-          schema:
-            type: string
-            enum: [average, max, min]
-            default: average
-          description: Data resolution/aggregation method
+      description: |
+        Retrieve Round-Robin Database metrics for graphing.
+        
+        **Note:** This endpoint extracts parameters from the request internally.
+        Parameters are handled automatically by the backend.
       responses:
         '200':
           description: RRD time-series data
@@ -648,25 +634,19 @@ paths:
   /acl_info:
     get:
       tags: [ACL]
-      summary: Get ACL information
-      description: Get access control list information for identities
-      parameters:
-        - name: identity_hash
-          in: query
-          schema:
-            type: string
-            pattern: '^0x[0-9a-fA-F]{2}$'
-          description: Identity hash
-          example: "0x42"
-        - name: identity_name
-          in: query
-          schema:
-            type: string
-          description: Identity name
-          example: "General"
+      summary: Get ACL information for all identities
+      description: |
+        Get ACL configuration and statistics for all registered identities.
+        
+        Returns information including:
+        - Identity name, type, and hash
+        - Max clients allowed
+        - Number of authenticated clients
+        - Password configuration status
+        - Read-only access setting
       responses:
         '200':
-          description: ACL information
+          description: ACL information for all identities
           content:
             application/json:
               schema:
@@ -676,6 +656,44 @@ paths:
                     type: boolean
                   data:
                     type: object
+                    properties:
+                      acls:
+                        type: array
+                        items:
+                          type: object
+                          properties:
+                            name:
+                              type: string
+                              example: "repeater"
+                            type:
+                              type: string
+                              enum: [repeater, room_server]
+                              example: "repeater"
+                            hash:
+                              type: string
+                              pattern: '^0x[0-9a-fA-F]{2}$'
+                              example: "0x42"
+                            max_clients:
+                              type: integer
+                              example: 100
+                            authenticated_clients:
+                              type: integer
+                              example: 5
+                            has_admin_password:
+                              type: boolean
+                              example: true
+                            has_guest_password:
+                              type: boolean
+                              example: true
+                            allow_read_only:
+                              type: boolean
+                              example: true
+                      total_identities:
+                        type: integer
+                        example: 3
+                      total_authenticated_clients:
+                        type: integer
+                        example: 15
 
   /acl_clients:
     get: