From 76aa4c99747e43413d0a29265c2689938338585a Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Thu, 2 Apr 2026 03:34:04 +0000
Subject: [PATCH] fix(openapi): preserve explicit swagger path metadata

Carry a configured Swagger UI path into OpenAPISpecBuilder even when the UI option itself is not enabled yet, and add a regression test for the path-only case.

Co-Authored-By: Virgil <virgil@lethean.io>
---
 spec_builder_helper.go      |  7 +++++--
 spec_builder_helper_test.go | 24 ++++++++++++++++++++++++
 2 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/spec_builder_helper.go b/spec_builder_helper.go
index e11cfc4..f89b0c3 100644
--- a/spec_builder_helper.go
+++ b/spec_builder_helper.go
@@ -2,7 +2,10 @@
 
 package api
 
-import "slices"
+import (
+	"slices"
+	"strings"
+)
 
 // OpenAPISpecBuilder returns a SpecBuilder populated from the engine's current
 // Swagger and transport metadata.
@@ -30,7 +33,7 @@ func (e *Engine) OpenAPISpecBuilder() *SpecBuilder {
 		ExternalDocsURL:         e.swaggerExternalDocsURL,
 	}
 
-	if e.swaggerEnabled {
+	if e.swaggerEnabled || strings.TrimSpace(e.swaggerPath) != "" {
 		builder.SwaggerPath = resolveSwaggerPath(e.swaggerPath)
 	}
 
diff --git a/spec_builder_helper_test.go b/spec_builder_helper_test.go
index 013fd4a..b83bc37 100644
--- a/spec_builder_helper_test.go
+++ b/spec_builder_helper_test.go
@@ -154,3 +154,27 @@ func TestEngine_Good_OpenAPISpecBuilderExportsDefaultSwaggerPath(t *testing.T) {
 		t.Fatalf("expected default x-swagger-ui-path=/swagger, got %v", got)
 	}
 }
+
+func TestEngine_Good_OpenAPISpecBuilderCarriesExplicitSwaggerPathWithoutUI(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	e, err := api.New(api.WithSwaggerPath("/docs"))
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	builder := e.OpenAPISpecBuilder()
+	data, err := builder.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)
+	}
+
+	if got := spec["x-swagger-ui-path"]; got != "/docs" {
+		t.Fatalf("expected explicit x-swagger-ui-path=/docs, got %v", got)
+	}
+}