feat(doc/gui): attach Scalar/OpenAPI

cmd/thv/app/server.go

@@ -11,8 +11,9 @@ import (
 )
 
 var (
-	host string
-	port int
+	host       string
+	port       int
+	enableDocs bool
 )
 
 var serveCmd = &cobra.Command{
@@ -28,11 +29,13 @@ var serveCmd = &cobra.Command{
 		debugMode, _ := cmd.Flags().GetBool("debug")
 
 		address := fmt.Sprintf("%s:%d", host, port)
-		return s.Serve(ctx, address, debugMode)
+		return s.Serve(ctx, address, debugMode, enableDocs)
 	},
 }
 
 func init() {
 	serveCmd.Flags().StringVar(&host, "host", "127.0.0.1", "Host address to bind the server to")
 	serveCmd.Flags().IntVar(&port, "port", 8080, "Port to bind the server to")
+	serveCmd.Flags().BoolVar(&enableDocs, "openapi", false,
+		"Enable OpenAPI documentation endpoints (/api/openapi.json and /api/doc)")
 }

docs/swagger.json

@@ -0,0 +1,7 @@
+{
+    "components": {"schemas":{"runtime.ContainerInfo":{"properties":{"created":{"description":"Created is the container creation timestamp","type":"string"},"id":{"description":"ID is the container ID","type":"string"},"image":{"description":"Image is the container image","type":"string"},"labels":{"additionalProperties":{"type":"string"},"description":"Labels is the container labels","type":"object"},"name":{"description":"Name is the container name","type":"string"},"ports":{"description":"Ports is the container port mappings","items":{"$ref":"#/components/schemas/runtime.PortMapping"},"type":"array"},"state":{"description":"State is the container state","type":"string"},"status":{"description":"Status is the container status","type":"string"}},"type":"object"},"runtime.PortMapping":{"properties":{"containerPort":{"description":"ContainerPort is the port inside the container","type":"integer"},"hostPort":{"description":"HostPort is the port on the host","type":"integer"},"protocol":{"description":"Protocol is the protocol (tcp, udp)","type":"string"}},"type":"object"},"secrets.SecretParameter":{"properties":{"name":{"type":"string"},"target":{"type":"string"}},"type":"object"},"v1.createRequest":{"description":"Request to create a new server","properties":{"authz_config":{"description":"Authorization configuration","type":"string"},"cmd_arguments":{"description":"Command arguments to pass to the container","items":{"type":"string"},"type":"array","uniqueItems":false},"env_vars":{"description":"Environment variables to set in the container","items":{"type":"string"},"type":"array","uniqueItems":false},"host":{"description":"Host to bind to","type":"string"},"image":{"description":"Docker image to use","type":"string"},"name":{"description":"Name of the server","type":"string"},"oidc":{"$ref":"#/components/schemas/v1.oidcOptions"},"permission_profile":{"description":"Permission profile to apply","type":"string"},"secrets":{"description":"Secret parameters to inject","items":{"$ref":"#/components/schemas/secrets.SecretParameter"},"type":"array","uniqueItems":false},"target_port":{"description":"Port to expose from the container","type":"integer"},"transport":{"description":"Transport configuration","type":"string"},"volumes":{"description":"Volume mounts","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"v1.createServerResponse":{"description":"Response after successfully creating a server","properties":{"name":{"description":"Name of the created server","type":"string"},"port":{"description":"Port the server is listening on","type":"integer"}},"type":"object"},"v1.oidcOptions":{"description":"OIDC configuration options","properties":{"audience":{"description":"Expected audience","type":"string"},"client_id":{"description":"OAuth2 client ID","type":"string"},"issuer":{"description":"OIDC issuer URL","type":"string"},"jwks_url":{"description":"JWKS URL for key verification","type":"string"}},"type":"object"},"v1.serverListResponse":{"description":"Response containing a list of servers","properties":{"servers":{"description":"List of container information for each server","items":{"$ref":"#/components/schemas/runtime.ContainerInfo"},"type":"array","uniqueItems":false}},"type":"object"},"v1.versionResponse":{"properties":{"version":{"type":"string"}},"type":"object"}}},
+    "info": {"description":"This is the ToolHive API server.","title":"ToolHive API","version":"1.0"},
+    "externalDocs": {"description":"","url":""},
+    "paths": {"/api/openapi.json":{"get":{"description":"Returns the OpenAPI specification for the API","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OpenAPI specification"}},"summary":"Get OpenAPI specification","tags":["system"]}},"/api/v1beta/servers":{"get":{"description":"Get a list of all running servers","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1.serverListResponse"}}},"description":"OK"}},"summary":"List all servers","tags":["servers"]},"post":{"description":"Create and start a new server","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1.createRequest"}}},"description":"Create server request","required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1.createServerResponse"}}},"description":"Created"},"400":{"content":{"application/json":{"schema":{"type":"string"}}},"description":"Bad Request"},"409":{"content":{"application/json":{"schema":{"type":"string"}}},"description":"Conflict"}},"summary":"Create a new server","tags":["servers"]}},"/api/v1beta/servers/{name}":{"delete":{"description":"Delete a server","parameters":[{"description":"Server name","in":"path","name":"name","required":true,"schema":{"type":"string"}},{"description":"Force deletion","in":"query","name":"force","schema":{"type":"boolean"}}],"responses":{"204":{"content":{"application/json":{"schema":{"type":"string"}}},"description":"No Content"},"404":{"content":{"application/json":{"schema":{"type":"string"}}},"description":"Not Found"}},"summary":"Delete a server","tags":["servers"]},"get":{"description":"Get details of a specific server","parameters":[{"description":"Server name","in":"path","name":"name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/runtime.ContainerInfo"}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"type":"string"}}},"description":"Not Found"}},"summary":"Get server details","tags":["servers"]}},"/api/v1beta/servers/{name}/restart":{"post":{"description":"Restart a running server","parameters":[{"description":"Server name","in":"path","name":"name","required":true,"schema":{"type":"string"}}],"responses":{"204":{"content":{"application/json":{"schema":{"type":"string"}}},"description":"No Content"},"404":{"content":{"application/json":{"schema":{"type":"string"}}},"description":"Not Found"}},"summary":"Restart a server","tags":["servers"]}},"/api/v1beta/servers/{name}/stop":{"post":{"description":"Stop a running server","parameters":[{"description":"Server name","in":"path","name":"name","required":true,"schema":{"type":"string"}}],"responses":{"204":{"content":{"application/json":{"schema":{"type":"string"}}},"description":"No Content"},"404":{"content":{"application/json":{"schema":{"type":"string"}}},"description":"Not Found"}},"summary":"Stop a server","tags":["servers"]}},"/api/v1beta/version":{"get":{"description":"Returns the current version of the server","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1.versionResponse"}}},"description":"OK"}},"summary":"Get server version","tags":["version"]}},"/health":{"get":{"description":"Check if the API is healthy","responses":{"204":{"content":{"application/json":{"schema":{"type":"string"}}},"description":"No Content"}},"summary":"Health check","tags":["system"]}}},
+    "openapi": "3.1.0"
+}