Skip to content

Commit

Permalink
docs(openapi): update API documentation and specifications (#655)
Browse files Browse the repository at this point in the history 
## What type of PR is this?

/kind documentation

## What this PR does / why we need it:

This PR updates the OpenAPI documentation and specifications. It
includes better API descriptions, adds documentation for the pod logs
streaming endpoint, updates the search pattern documentation to include
natural language support, and adds the LogEntry schema definition to the
OpenAPI spec.

## Which issue(s) this PR fixes:

Fixes #
  • Loading branch information
@elliotxx
elliotxx authored Nov 27, 2024
1 parent 6d7cb7f commit b2f1515
Show file tree
Hide file tree
Showing 7 changed files with 422 additions and 10 deletions.
85 changes: 83 additions & 2 deletions api/openapispec/docs.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,73 @@ var doc = `{
}
}
},
"/insight/aggregator/pod/{cluster}/{namespace}/{name}/log": {
"get": {
"description": "This endpoint streams pod logs in real-time using SSE. It supports container selection and automatic reconnection.",
"produces": [
"text/event-stream"
],
"tags": [
"insight"
],
"summary": "Stream pod logs using Server-Sent Events",
"parameters": [
{
"type": "string",
"description": "The cluster name",
"name": "cluster",
"in": "path",
"required": true
},
{
"type": "string",
"description": "The namespace name",
"name": "namespace",
"in": "path",
"required": true
},
{
"type": "string",
"description": "The pod name",
"name": "name",
"in": "path",
"required": true
},
{
"type": "string",
"description": "The container name (optional if pod has only one container)",
"name": "container",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/aggregator.LogEntry"
}
},
"400": {
"description": "Bad Request",
"schema": {
"type": "string"
}
},
"401": {
"description": "Unauthorized",
"schema": {
"type": "string"
}
},
"404": {
"description": "Not Found",
"schema": {
"type": "string"
}
}
}
}
},
"/rest-api/v1/cluster/config/file": {
"post": {
"description": "Uploads a KubeConfig file for cluster, with a maximum size of 2MB.",
Expand Down Expand Up @@ -1637,7 +1704,7 @@ var doc = `{
},
{
"type": "string",
"description": "The search pattern. Can be either sql or dsl. Required",
"description": "The search pattern. Can be either sql, dsl or nl. Required",
"name": "pattern",
"in": "query",
"required": true
Expand Down Expand Up @@ -1704,6 +1771,20 @@ var doc = `{
}
},
"definitions": {
"aggregator.LogEntry": {
"type": "object",
"properties": {
"content": {
"type": "string"
},
"error": {
"type": "string"
},
"timestamp": {
"type": "string"
}
}
},
"cluster.ClusterPayload": {
"type": "object",
"properties": {
Expand Down Expand Up @@ -1957,7 +2038,7 @@ var SwaggerInfo = swaggerInfo{
BasePath: "",
Schemes: []string{},
Title: "Karpor",
Description: "",
Description: "Karpor is a brand new Kubernetes visualization tool that focuses on search, insights, and AI at its core",
}

type s struct{}
Expand Down
84 changes: 83 additions & 1 deletion api/openapispec/swagger.json
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
{
"swagger": "2.0",
"info": {
"description": "Karpor is a brand new Kubernetes visualization tool that focuses on search, insights, and AI at its core",
"title": "Karpor",
"contact": {},
"version": "1.0"
Expand Down Expand Up @@ -85,6 +86,73 @@
}
}
},
"/insight/aggregator/pod/{cluster}/{namespace}/{name}/log": {
"get": {
"description": "This endpoint streams pod logs in real-time using SSE. It supports container selection and automatic reconnection.",
"produces": [
"text/event-stream"
],
"tags": [
"insight"
],
"summary": "Stream pod logs using Server-Sent Events",
"parameters": [
{
"type": "string",
"description": "The cluster name",
"name": "cluster",
"in": "path",
"required": true
},
{
"type": "string",
"description": "The namespace name",
"name": "namespace",
"in": "path",
"required": true
},
{
"type": "string",
"description": "The pod name",
"name": "name",
"in": "path",
"required": true
},
{
"type": "string",
"description": "The container name (optional if pod has only one container)",
"name": "container",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/aggregator.LogEntry"
}
},
"400": {
"description": "Bad Request",
"schema": {
"type": "string"
}
},
"401": {
"description": "Unauthorized",
"schema": {
"type": "string"
}
},
"404": {
"description": "Not Found",
"schema": {
"type": "string"
}
}
}
}
},
"/rest-api/v1/cluster/config/file": {
"post": {
"description": "Uploads a KubeConfig file for cluster, with a maximum size of 2MB.",
Expand Down Expand Up @@ -1620,7 +1688,7 @@
},
{
"type": "string",
"description": "The search pattern. Can be either sql or dsl. Required",
"description": "The search pattern. Can be either sql, dsl or nl. Required",
"name": "pattern",
"in": "query",
"required": true
Expand Down Expand Up @@ -1687,6 +1755,20 @@
}
},
"definitions": {
"aggregator.LogEntry": {
"type": "object",
"properties": {
"content": {
"type": "string"
},
"error": {
"type": "string"
},
"timestamp": {
"type": "string"
}
}
},
"cluster.ClusterPayload": {
"type": "object",
"properties": {
Expand Down
59 changes: 58 additions & 1 deletion api/openapispec/swagger.yaml
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,13 @@
definitions:
aggregator.LogEntry:
properties:
content:
type: string
error:
type: string
timestamp:
type: string
type: object
cluster.ClusterPayload:
properties:
description:
Expand Down Expand Up @@ -172,6 +181,8 @@ definitions:
type: object
info:
contact: {}
description: Karpor is a brand new Kubernetes visualization tool that focuses on
search, insights, and AI at its core
title: Karpor
version: "1.0"
paths:
Expand Down Expand Up @@ -227,6 +238,52 @@ paths:
summary: List all available endpoints
tags:
- debug
/insight/aggregator/pod/{cluster}/{namespace}/{name}/log:
get:
description: This endpoint streams pod logs in real-time using SSE. It supports
container selection and automatic reconnection.
parameters:
- description: The cluster name
in: path
name: cluster
required: true
type: string
- description: The namespace name
in: path
name: namespace
required: true
type: string
- description: The pod name
in: path
name: name
required: true
type: string
- description: The container name (optional if pod has only one container)
in: query
name: container
type: string
produces:
- text/event-stream
responses:
"200":
description: OK
schema:
$ref: '#/definitions/aggregator.LogEntry'
"400":
description: Bad Request
schema:
type: string
"401":
description: Unauthorized
schema:
type: string
"404":
description: Not Found
schema:
type: string
summary: Stream pod logs using Server-Sent Events
tags:
- insight
/rest-api/v1/cluster/{clusterName}:
delete:
description: This endpoint deletes the cluster resource by name.
Expand Down Expand Up @@ -1254,7 +1311,7 @@ paths:
name: query
required: true
type: string
- description: The search pattern. Can be either sql or dsl. Required
- description: The search pattern. Can be either sql, dsl or nl. Required
in: query
name: pattern
required: true
Expand Down
6 changes: 4 additions & 2 deletions cmd/karpor/main.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,10 @@ import (
"k8s.io/component-base/cli"
)

// @title Karpor
// @version 1.0
// @title Karpor
// @version 1.0
// @description Karpor is a brand new Kubernetes visualization tool that focuses on search, insights, and AI at its core

func main() {
ctx := genericapiserver.SetupSignalContext()

Expand Down
Loading

0 comments on commit b2f1515

Please sign in to comment.