From f6a82a3b7cc6d71100113cd1210ba00b7a2e1522 Mon Sep 17 00:00:00 2001
From: yusing <yusing.wys@gmail.com>
Date: Sun, 22 Feb 2026 19:54:56 +0800
Subject: [PATCH] docs(api): update swagger docs with field descriptions and
 operationId rename

- Add minimum: 0 validation to LogRetention properties (days, keep_size, last)
- Add "interned" descriptions to fstype, path, and name fields
- Rename operationId and x-id from "routes" to "list" for GET /route endpoint
---
 internal/api/v1/docs/swagger.json            | 10 ++++++++--
 internal/api/v1/docs/swagger.yaml            | 12 +++++++++---
 internal/api/v1/route/{routes.go => list.go} |  2 +-
 3 files changed, 18 insertions(+), 6 deletions(-)
 rename internal/api/v1/route/{routes.go => list.go} (98%)

diff --git a/internal/api/v1/docs/swagger.json b/internal/api/v1/docs/swagger.json
index bc0759c0..5f979c8e 100644
--- a/internal/api/v1/docs/swagger.json
+++ b/internal/api/v1/docs/swagger.json
@@ -2946,8 +2946,8 @@
             }
           }
         },
-        "x-id": "routes",
-        "operationId": "routes"
+        "x-id": "list",
+        "operationId": "list"
       }
     },
     "/route/playground": {
@@ -4844,16 +4844,19 @@
       "properties": {
         "days": {
           "type": "integer",
+          "minimum": 0,
           "x-nullable": false,
           "x-omitempty": false
         },
         "keep_size": {
           "type": "integer",
+          "minimum": 0,
           "x-nullable": false,
           "x-omitempty": false
         },
         "last": {
           "type": "integer",
+          "minimum": 0,
           "x-nullable": false,
           "x-omitempty": false
         }
@@ -6644,11 +6647,13 @@
           "x-omitempty": false
         },
         "fstype": {
+          "description": "interned",
           "type": "string",
           "x-nullable": false,
           "x-omitempty": false
         },
         "path": {
+          "description": "interned",
           "type": "string",
           "x-nullable": false,
           "x-omitempty": false
@@ -6995,6 +7000,7 @@
           "x-omitempty": false
         },
         "name": {
+          "description": "interned",
           "type": "string",
           "x-nullable": false,
           "x-omitempty": false
diff --git a/internal/api/v1/docs/swagger.yaml b/internal/api/v1/docs/swagger.yaml
index e2240f20..8053ae06 100644
--- a/internal/api/v1/docs/swagger.yaml
+++ b/internal/api/v1/docs/swagger.yaml
@@ -767,10 +767,13 @@ definitions:
   LogRetention:
     properties:
       days:
+        minimum: 0
         type: integer
       keep_size:
+        minimum: 0
         type: integer
       last:
+        minimum: 0
         type: integer
     type: object
   MetricsPeriod:
@@ -1690,8 +1693,10 @@ definitions:
       free:
         type: integer
       fstype:
+        description: interned
         type: string
       path:
+        description: interned
         type: string
       total:
         type: number
@@ -1832,12 +1837,12 @@ definitions:
         type: string
       kernel_version:
         type: string
+      load_avg_5m:
+        type: string
       load_avg_15m:
         type: string
       load_avg_1m:
         type: string
-      load_avg_5m:
-        type: string
       mem_pct:
         type: string
       mem_total:
@@ -1886,6 +1891,7 @@ definitions:
       high:
         type: number
       name:
+        description: interned
         type: string
       temperature:
         type: number
@@ -3932,7 +3938,7 @@ paths:
       tags:
       - route
       - websocket
-      x-id: routes
+      x-id: list
   /route/playground:
     post:
       consumes:
diff --git a/internal/api/v1/route/routes.go b/internal/api/v1/route/list.go
similarity index 98%
rename from internal/api/v1/route/routes.go
rename to internal/api/v1/route/list.go
index 37b003df..de9e13cd 100644
--- a/internal/api/v1/route/routes.go
+++ b/internal/api/v1/route/list.go
@@ -15,7 +15,7 @@ import (
 
 type RouteType route.Route // @name Route
 
-// @x-id				"routes"
+// @x-id				"list"
 // @BasePath		/api/v1
 // @Summary		List routes
 // @Description	List routes