docs: update openapi doc

- Add new endpoint `/insight/issue/interpret/stream` for AI-based issue interpretation - Define new schemas `ai.AuditData` and `ai.IssueGroup` for AI-related data - Update OpenAPI specification and documentation to reflect new endpoint and schemas - Modify handler to reference `ai.AuditData` instead of `scanner.AuditData` This feature enables the system to provide detailed AI-driven interpretations of scanner issues, enhancing the insight capabilities of the platform.
KusionStack · Jan 8, 2025 · 09abf6f · 09abf6f
1 parent f2348f6
commit 09abf6f
Show file tree

Hide file tree

Showing 5 changed files with 510 additions and 122 deletions.
diff --git a/api/openapispec/docs.go b/api/openapispec/docs.go
@@ -376,6 +376,70 @@ var doc = `{
                 }
             }
         },
+        "/insight/issue/interpret/stream": {
+            "post": {
+                "description": "This endpoint analyzes scanner issues using AI to provide detailed interpretation and insights",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "text/event-stream"
+                ],
+                "tags": [
+                    "insight"
+                ],
+                "summary": "Interpret scanner issues using AI",
+                "parameters": [
+                    {
+                        "description": "The audit data to interpret",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/scanner.InterpretRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/ai.InterpretEvent"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    "429": {
+                        "description": "Too Many Requests",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    "500": {
+                        "description": "Internal Server Error",
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                }
+            }
+        },
         "/insight/yaml/interpret/stream": {
             "post": {
                 "description": "This endpoint analyzes YAML content using AI to provide detailed interpretation and insights",
@@ -413,6 +477,24 @@ var doc = `{
                             "type": "string"
                         }
                     },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    "429": {
+                        "description": "Too Many Requests",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
                     "500": {
                         "description": "Internal Server Error",
                         "schema": {
@@ -969,7 +1051,7 @@ var doc = `{
                     "200": {
                         "description": "Audit results",
                         "schema": {
-                            "$ref": "#/definitions/scanner.AuditData"
+                            "$ref": "#/definitions/ai.AuditData"
                         }
                     },
                     "400": {
@@ -2067,6 +2149,29 @@ var doc = `{
                 }
             }
         },
+        "ai.AuditData": {
+            "type": "object",
+            "properties": {
+                "bySeverity": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "integer"
+                    }
+                },
+                "issueGroups": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/ai.IssueGroup"
+                    }
+                },
+                "issueTotal": {
+                    "type": "integer"
+                },
+                "resourceTotal": {
+                    "type": "integer"
+                }
+            }
+        },
         "ai.DiagnosisEvent": {
             "type": "object",
             "properties": {
@@ -2116,6 +2221,20 @@ var doc = `{
                 }
             }
         },
+        "ai.IssueGroup": {
+            "type": "object",
+            "properties": {
+                "issue": {
+                    "$ref": "#/definitions/scanner.Issue"
+                },
+                "resourceGroups": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/entity.ResourceGroup"
+                    }
+                }
+            }
+        },
         "cluster.ClusterPayload": {
             "type": "object",
             "properties": {
@@ -2296,26 +2415,16 @@ var doc = `{
                 }
             }
         },
-        "scanner.AuditData": {
+        "scanner.InterpretRequest": {
             "type": "object",
             "properties": {
-                "bySeverity": {
-                    "type": "object",
-                    "additionalProperties": {
-                        "type": "integer"
-                    }
-                },
-                "issueGroups": {
-                    "type": "array",
-                    "items": {
-                        "$ref": "#/definitions/scanner.IssueGroup"
-                    }
-                },
-                "issueTotal": {
-                    "type": "integer"
+                "auditData": {
+                    "description": "The audit data to interpret",
+                    "$ref": "#/definitions/ai.AuditData"
                 },
-                "resourceTotal": {
-                    "type": "integer"
+                "language": {
+                    "description": "Language for interpretation",
+                    "type": "string"
                 }
             }
         },
@@ -2340,20 +2449,6 @@ var doc = `{
                 }
             }
         },
-        "scanner.IssueGroup": {
-            "type": "object",
-            "properties": {
-                "issue": {
-                    "$ref": "#/definitions/scanner.Issue"
-                },
-                "resourceGroups": {
-                    "type": "array",
-                    "items": {
-                        "$ref": "#/definitions/entity.ResourceGroup"
-                    }
-                }
-            }
-        },
         "unstructured.Unstructured": {
             "type": "object",
             "properties": {