feat(api): add OpenAPI server metadata

Co-Authored-By: Virgil <virgil@lethean.io>

cmd/api/cmd_spec.go

@@ -5,6 +5,7 @@ package api
 import (
 	"fmt"
 	"os"
+	"strings"
 
 	"forge.lthn.ai/core/cli/pkg/cli"
 
@@ -18,6 +19,7 @@ func addSpecCommand(parent *cli.Command) {
 		title       string
 		description string
 		version     string
+		servers     string
 	)
 
 	cmd := cli.NewCommand("spec", "Generate OpenAPI specification", "", func(cmd *cli.Command, args []string) error {
@@ -27,6 +29,7 @@ func addSpecCommand(parent *cli.Command) {
 			Title:       title,
 			Description: description,
 			Version:     version,
+			Servers:     parseServers(servers),
 		}
 
 		// Start with the default tool bridge — future versions will
@@ -51,6 +54,23 @@ func addSpecCommand(parent *cli.Command) {
 	cli.StringFlag(cmd, &title, "title", "t", "Lethean Core API", "API title in spec")
 	cli.StringFlag(cmd, &description, "description", "d", "Lethean Core API", "API description in spec")
 	cli.StringFlag(cmd, &version, "version", "V", "1.0.0", "API version in spec")
+	cli.StringFlag(cmd, &servers, "server", "S", "", "Comma-separated OpenAPI server URL(s)")
 
 	parent.AddCommand(cmd)
 }
+
+func parseServers(raw string) []string {
+	if raw == "" {
+		return nil
+	}
+
+	parts := strings.Split(raw, ",")
+	servers := make([]string, 0, len(parts))
+	for _, part := range parts {
+		if server := strings.TrimSpace(part); server != "" {
+			servers = append(servers, server)
+		}
+	}
+
+	return servers
+}

cmd/api/cmd_test.go

@@ -59,6 +59,9 @@ func TestAPISpecCmd_Good_JSON(t *testing.T) {
 	if specCmd.Flag("version") == nil {
 		t.Fatal("expected --version flag on spec command")
 	}
+	if specCmd.Flag("server") == nil {
+		t.Fatal("expected --server flag on spec command")
+	}
 }
 
 func TestAPISpecCmd_Good_CustomDescription(t *testing.T) {
@@ -91,6 +94,37 @@ func TestAPISpecCmd_Good_CustomDescription(t *testing.T) {
 	}
 }
 
+func TestAPISpecCmd_Good_ServerFlagAddsServers(t *testing.T) {
+	root := &cli.Command{Use: "root"}
+	AddAPICommands(root)
+
+	outputFile := t.TempDir() + "/spec.json"
+	root.SetArgs([]string{"api", "spec", "--server", "https://api.example.com,/", "--output", outputFile})
+	root.SetErr(new(bytes.Buffer))
+
+	if err := root.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data, err := os.ReadFile(outputFile)
+	if err != nil {
+		t.Fatalf("expected spec file to be written: %v", err)
+	}
+
+	var spec map[string]any
+	if err := json.Unmarshal(data, &spec); err != nil {
+		t.Fatalf("expected valid JSON spec, got error: %v", err)
+	}
+
+	servers, ok := spec["servers"].([]any)
+	if !ok {
+		t.Fatalf("expected servers array in generated spec, got %T", spec["servers"])
+	}
+	if len(servers) != 2 {
+		t.Fatalf("expected 2 servers, got %d", len(servers))
+	}
+}
+
 func TestAPISDKCmd_Bad_NoLang(t *testing.T) {
 	root := &cli.Command{Use: "root"}
 	AddAPICommands(root)

openapi.go

@@ -14,6 +14,7 @@ type SpecBuilder struct {
 	Title       string
 	Description string
 	Version     string
+	Servers     []string
 }
 
 // Build generates the complete OpenAPI 3.1 JSON spec.
@@ -36,6 +37,19 @@ func (sb *SpecBuilder) Build(groups []RouteGroup) ([]byte, error) {
 		},
 	}
 
+	if len(sb.Servers) > 0 {
+		servers := make([]map[string]any, 0, len(sb.Servers))
+		for _, server := range sb.Servers {
+			if server == "" {
+				continue
+			}
+			servers = append(servers, map[string]any{"url": server})
+		}
+		if len(servers) > 0 {
+			spec["servers"] = servers
+		}
+	}
+
 	// Add component schemas for the response envelope.
 	spec["components"] = map[string]any{
 		"schemas": map[string]any{

openapi_test.go

@@ -632,3 +632,42 @@ func TestSpecBuilder_Bad_InfoFields(t *testing.T) {
 		t.Fatalf("expected version=1.0.0, got %v", info["version"])
 	}
 }
+
+func TestSpecBuilder_Good_Servers(t *testing.T) {
+	sb := &api.SpecBuilder{
+		Title:   "Test",
+		Version: "1.0.0",
+		Servers: []string{
+			"https://api.example.com",
+			"/",
+			"",
+		},
+	}
+
+	data, err := sb.Build(nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var spec map[string]any
+	if err := json.Unmarshal(data, &spec); err != nil {
+		t.Fatalf("invalid JSON: %v", err)
+	}
+
+	servers, ok := spec["servers"].([]any)
+	if !ok {
+		t.Fatalf("expected servers array, got %T", spec["servers"])
+	}
+	if len(servers) != 2 {
+		t.Fatalf("expected 2 non-empty servers, got %d", len(servers))
+	}
+
+	first := servers[0].(map[string]any)
+	if first["url"] != "https://api.example.com" {
+		t.Fatalf("expected first server url=%q, got %v", "https://api.example.com", first["url"])
+	}
+	second := servers[1].(map[string]any)
+	if second["url"] != "/" {
+		t.Fatalf("expected second server url=%q, got %v", "/", second["url"])
+	}
+}