From 5e89dc8ae718927267522967efb7c9749c5c6b61 Mon Sep 17 00:00:00 2001
From: Alan Richardson <alan@compendiumdev.co.uk>
Date: Thu, 16 Jul 2026 22:38:15 +0100
Subject: [PATCH] Add Swagger UI for API Challenges

---
 .../challenge/gui/ChallengerWebGUI.java       |   7 +
 .../uirouting/UiPagesAreReachableTest.java    |  84 +++++++++
 .../ThingifierAutoDocGenRouting.java          |  47 ++++-
 .../adapter/javalin/JavalinHttpServer.java    |  95 ++++++++++
 .../RestApiDocumentationGenerator.java        |   1 +
 .../thingifier/swaggerizer/SwaggerUiPage.java | 176 ++++++++++++++++++
 .../thingifier/swaggerizer/Swaggerizer.java   |  52 ++++++
 7 files changed, 454 insertions(+), 8 deletions(-)
 create mode 100644 thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerUiPage.java

diff --git a/challenger/src/main/java/uk/co/compendiumdev/challenge/gui/ChallengerWebGUI.java b/challenger/src/main/java/uk/co/compendiumdev/challenge/gui/ChallengerWebGUI.java
index 7fc491fb..ee9e7bea 100644
--- a/challenger/src/main/java/uk/co/compendiumdev/challenge/gui/ChallengerWebGUI.java
+++ b/challenger/src/main/java/uk/co/compendiumdev/challenge/gui/ChallengerWebGUI.java
@@ -115,6 +115,7 @@ function setMenuNavBasedOnUrl(){
                                 <ul>
                                     <li><a href="/practice-modes/simpleapi">About Simple API</a>
                                     <li><a href="/simpleapi/docs">API Docs</a>
+                                    <li><a href="/simpleapi/docs/swagger-ui">Swagger UI</a>
                                     <li><a href="/simpleapi/gui/entities">Data Explorer</a></li>
                                     <li><a href="/practice-modes/simpleapi-openapi">OpenAPI File</a>
                                 </ul>
@@ -124,6 +125,7 @@ function setMenuNavBasedOnUrl(){
                                 <ul>
                                     <li><a href="/apichallenges">About API Challenges</a></li>
                                     <li><a href="/docs">API Docs</a></li>
+                                    <li><a href="/docs/swagger-ui">Swagger UI</a></li>
                                     <li><a href="/gui/challenges">Progress</a></li>
                                     <li><a href="/gui/entities">Data Explorer</a></li>
                                     <li><a href="/apichallenges/solutions">Solutions</a></li>
@@ -135,6 +137,7 @@ function setMenuNavBasedOnUrl(){
                                 <ul>
                                     <li><a href="/practice-modes/simulation">About API Simulator</a></li>
                                     <li><a href="/sim/docs">API Docs</a></li>
+                                    <li><a href="/sim/docs/swagger-ui">Swagger UI</a></li>
                                     <li><a href="/sim/docs/swagger">[Download Open API File]</a></li>
 
                                 </ul>
@@ -144,6 +147,7 @@ function setMenuNavBasedOnUrl(){
                                 <ul>
                                     <li><a href="/practice-modes/mirror">About HTTP Mirror</a></li>
                                     <li><a href="/mirror/docs">Mirror API Docs</a></li>
+                                    <li><a href="/mirror/docs/swagger-ui">Swagger UI</a></li>
                                     <li><a href="/mirror/docs/swagger">[Download Open API File]</a></li>
 
                                 </ul>
@@ -260,6 +264,9 @@ function setMenuNavBasedOnUrl(){
         }
         siteMap.addUrl("https://apichallenges.eviltester.com", SEO_FIXED_LASTMOD.toString());
         siteMap.addUrl("https://apichallenges.eviltester.com/docs", SEO_FIXED_LASTMOD.toString());
+        siteMap.addUrl(
+                "https://apichallenges.eviltester.com/docs/swagger-ui",
+                SEO_FIXED_LASTMOD.toString());
         siteMap.addUrl(
                 "https://apichallenges.eviltester.com/gui/challenges",
                 SEO_FIXED_LASTMOD.toString());
diff --git a/challenger/src/test/java/uk/co/compendiumdev/uirouting/UiPagesAreReachableTest.java b/challenger/src/test/java/uk/co/compendiumdev/uirouting/UiPagesAreReachableTest.java
index f6d5d191..982ee632 100644
--- a/challenger/src/test/java/uk/co/compendiumdev/uirouting/UiPagesAreReachableTest.java
+++ b/challenger/src/test/java/uk/co/compendiumdev/uirouting/UiPagesAreReachableTest.java
@@ -175,11 +175,92 @@ void canDownloadSwaggerFile() {
         Assertions.assertTrue(response.body.contains("\"openapi\" : \"3.0.1\","));
     }
 
+    @Test
+    void canFetchDefaultOpenApiJsonForSwaggerUi() {
+
+        final HttpResponseDetails response = http.send("/docs/openapi.json", "get");
+
+        Assertions.assertEquals(200, response.statusCode);
+        Assertions.assertNotNull(response.getHeader("Content-Type"));
+        Assertions.assertTrue(response.getHeader("Content-Type").contains("application/json"));
+        Assertions.assertTrue(response.body.contains("\"openapi\" : \"3.0.1\","));
+        Assertions.assertTrue(
+                response.body.indexOf("\"url\" : \"http://localhost:4567\"")
+                        < response.body.indexOf(
+                                "\"url\" : \"https://apichallenges.eviltester.com\""));
+    }
+
+    @Test
+    void staticAssetsAreServedBeforeGenericFallbackRoutes() {
+
+        HttpResponseDetails response = http.send("/css/default.css", "get");
+        Assertions.assertEquals(200, response.statusCode);
+        Assertions.assertTrue(response.getHeader("Content-Type").contains("text/css"));
+        Assertions.assertTrue(response.body.contains(".rootmenu"));
+
+        response = http.send("/js/toc.js", "get");
+        Assertions.assertEquals(200, response.statusCode);
+        Assertions.assertTrue(response.getHeader("Content-Type").contains("javascript"));
+        Assertions.assertTrue(response.body.contains("htmlTableOfContents"));
+
+        response = http.send("/favicon/site.webmanifest", "get");
+        Assertions.assertEquals(200, response.statusCode);
+        Assertions.assertTrue(response.getHeader("Content-Type").contains("manifest+json"));
+        Assertions.assertTrue(response.body.contains("icons"));
+    }
+
+    static Stream<Arguments> swaggerUiPageRoutes() {
+        List<Arguments> args = new ArrayList<>();
+        args.add(Arguments.of("/docs/swagger-ui", "/docs/openapi.json"));
+        args.add(Arguments.of("/simpleapi/docs/swagger-ui", "/simpleapi/docs/openapi.json"));
+        args.add(Arguments.of("/sim/docs/swagger-ui", "/sim/docs/openapi.json"));
+        args.add(Arguments.of("/mirror/docs/swagger-ui", "/mirror/docs/openapi.json"));
+        return args.stream();
+    }
+
+    @ParameterizedTest(name = "swagger ui page {0} references {1}")
+    @MethodSource("swaggerUiPageRoutes")
+    void swaggerUiPagesRenderAndReferenceMatchingOpenApiJson(
+            final String swaggerUiPath, final String openApiJsonPath) {
+
+        final HttpResponseDetails response = http.send(swaggerUiPath, "get");
+
+        Assertions.assertEquals(200, response.statusCode);
+        Assertions.assertNotNull(response.getHeader("Content-Type"));
+        Assertions.assertTrue(response.getHeader("Content-Type").contains("text/html"));
+        assertContainsHeaderAndFooter(response);
+        Assertions.assertTrue(
+                response.body.contains("https://unpkg.com/swagger-ui-dist/swagger-ui.css"));
+        Assertions.assertTrue(
+                response.body.contains("https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"));
+        Assertions.assertTrue(
+                response.body.contains(
+                        "https://unpkg.com/swagger-ui-dist/swagger-ui-standalone-preset.js"));
+        Assertions.assertTrue(response.body.contains("color-scheme:light"));
+        Assertions.assertTrue(response.body.contains("syntaxHighlight: {activated: false}"));
+        Assertions.assertTrue(response.body.contains("SwaggerUIBundle"));
+        Assertions.assertTrue(response.body.contains("url: \"" + openApiJsonPath + "\""));
+    }
+
+    @Test
+    void challengerMenuContainsSwaggerUiLinks() {
+
+        final HttpResponseDetails response = http.send("/", "get");
+
+        Assertions.assertEquals(200, response.statusCode);
+        Assertions.assertTrue(response.body.contains("href=\"/docs/swagger-ui\""));
+        Assertions.assertTrue(response.body.contains("href=\"/simpleapi/docs/swagger-ui\""));
+        Assertions.assertTrue(response.body.contains("href=\"/sim/docs/swagger-ui\""));
+        Assertions.assertTrue(response.body.contains("href=\"/mirror/docs/swagger-ui\""));
+    }
+
     @Test
     void docsPagesRenderPerApiSeoMetadata() {
 
         final HttpResponseDetails docsResponse = http.send("/docs", "get");
         Assertions.assertEquals(200, docsResponse.statusCode);
+        Assertions.assertTrue(docsResponse.body.contains("Open Swagger UI"));
+        Assertions.assertTrue(docsResponse.body.contains("href='/docs/swagger-ui'"));
         Assertions.assertTrue(
                 docsResponse.body.contains(
                         "<title>API Challenges API Documentation | API Challenges</title>"));
@@ -381,6 +462,9 @@ void sitemapUsesFixedLastmodForPhaseOneUrls() {
                 response.body.contains("<loc>https://apichallenges.eviltester.com</loc>"));
         Assertions.assertTrue(
                 response.body.contains("<loc>https://apichallenges.eviltester.com/docs</loc>"));
+        Assertions.assertTrue(
+                response.body.contains(
+                        "<loc>https://apichallenges.eviltester.com/docs/swagger-ui</loc>"));
         Assertions.assertTrue(
                 response.body.contains(
                         "<loc>https://apichallenges.eviltester.com/gui/challenges</loc>"));
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ThingifierAutoDocGenRouting.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ThingifierAutoDocGenRouting.java
index 43320ff4..426fdf9f 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ThingifierAutoDocGenRouting.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ThingifierAutoDocGenRouting.java
@@ -8,6 +8,7 @@
 import uk.co.compendiumdev.thingifier.api.docgen.ThingifierApiDocumentationDefn;
 import uk.co.compendiumdev.thingifier.htmlgui.htmlgen.DefaultGUIHTML;
 import uk.co.compendiumdev.thingifier.htmlgui.htmlgen.RestApiDocumentationGenerator;
+import uk.co.compendiumdev.thingifier.swaggerizer.SwaggerUiPage;
 import uk.co.compendiumdev.thingifier.swaggerizer.Swaggerizer;
 
 public class ThingifierAutoDocGenRouting {
@@ -20,12 +21,17 @@ public ThingifierAutoDocGenRouting(
         // configure it based on a thingifier
         ApiRoutingDefinition routingDefinitions =
                 new ApiRoutingDefinitionDocGenerator(thingifier).generate(apiDefn.getPathPrefix());
+        final String pathPrefix = apiDefn.getPathPrefix();
+        final String docsPath = "%s/docs".formatted(pathPrefix);
+        final String swaggerDownloadPath = "%s/docs/swagger".formatted(pathPrefix);
+        final String openApiPath = "%s/docs/openapi.json".formatted(pathPrefix);
+        final String swaggerUiPath = "%s/docs/swagger-ui".formatted(pathPrefix);
 
         // TODO: config to enable docs and configure the URL and add a meta tag for description and
         // additional headers
         // / - default for documentation
         get(
-                "%s/docs".formatted(apiDefn.getPathPrefix()),
+                docsPath,
                 (request, response) -> {
                     response.type("text/html");
                     response.status(200);
@@ -35,16 +41,40 @@ public ThingifierAutoDocGenRouting(
                                     apiDefn.getAdditionalRoutes(),
                                     apiDefn,
                                     apiDefn.getPathPrefix(),
-                                    "%s/docs".formatted(apiDefn.getPathPrefix()));
+                                    docsPath);
                 });
 
         // guiManagement.appendMenuItem("API documentation","/docs");
 
+        get(
+                openApiPath,
+                (request, response) -> {
+                    response.type("application/json");
+                    response.status(200);
+                    return new Swaggerizer(apiDefn)
+                            .asJsonWithPreferredServer(requestOrigin(request));
+                });
+
+        get(
+                swaggerUiPath,
+                (request, response) -> {
+                    response.type("text/html");
+                    response.status(200);
+                    return new SwaggerUiPage(
+                                    apiDefn,
+                                    guiManagement,
+                                    openApiPath,
+                                    docsPath,
+                                    swaggerDownloadPath,
+                                    swaggerUiPath)
+                            .html();
+                });
+
         // TODO: api config to enable swagger and configure the URL
         // TODO: move into swagger package
         // now that we have an api definition we should be able to generate swagger
         get(
-                "%s/docs/swagger".formatted(apiDefn.getPathPrefix()),
+                swaggerDownloadPath,
                 (request, response) -> {
                     String permissive = request.queryParam("permissive");
 
@@ -68,11 +98,12 @@ public ThingifierAutoDocGenRouting(
 
                     // TODO: the swaggerizer could be stored at a class level and allow caching to
                     // be used for the output
-                    if (permissive == null) {
-                        return new Swaggerizer(apiDefn).asJson();
-                    } else {
-                        return new Swaggerizer(apiDefn).asJson(true);
-                    }
+                    return new Swaggerizer(apiDefn)
+                            .asJsonWithPreferredServer(permissive != null, requestOrigin(request));
                 });
     }
+
+    private String requestOrigin(final HttpServerRequest request) {
+        return "%s://%s".formatted(request.scheme(), request.host());
+    }
 }
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/javalin/JavalinHttpServer.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/javalin/JavalinHttpServer.java
index a4f670c9..238221e3 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/javalin/JavalinHttpServer.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/javalin/JavalinHttpServer.java
@@ -4,6 +4,8 @@
 import io.javalin.http.Context;
 import io.javalin.http.HandlerType;
 import io.javalin.http.staticfiles.Location;
+import java.io.InputStream;
+import java.net.URLConnection;
 import java.nio.charset.StandardCharsets;
 import java.util.HashMap;
 import java.util.Map;
@@ -16,6 +18,11 @@
 import uk.co.compendiumdev.thingifier.api.response.ApiResponseError;
 
 public final class JavalinHttpServer implements AutoCloseable {
+    private static final String[] STATIC_ASSET_PREFIXES = {
+        "/css/", "/js/", "/favicon/", "/images/"
+    };
+    private static final String[] STATIC_ASSET_FILES = {"/robots.txt", "/sitemap.bak"};
+
     private final int port;
     private final String staticFilePath;
     private final HttpRouteRegistry registry;
@@ -39,6 +46,7 @@ public void start() {
                                         staticFiles.directory = staticFilePath;
                                         staticFiles.location = Location.CLASSPATH;
                                     });
+                            config.routes.before(this::serveClasspathStaticAsset);
                             for (HttpBeforeHandler beforeHandler : registry.beforeHandlers()) {
                                 config.routes.before(ctx -> runBefore(ctx, beforeHandler));
                             }
@@ -78,6 +86,93 @@ public void start() {
         app.start(port);
     }
 
+    private void serveClasspathStaticAsset(final Context ctx) throws Exception {
+        if (ctx.method() != HandlerType.GET && ctx.method() != HandlerType.HEAD) {
+            return;
+        }
+
+        final String path = ctx.path();
+        if (!isStaticAssetPath(path)) {
+            return;
+        }
+
+        final InputStream resource =
+                Thread.currentThread()
+                        .getContextClassLoader()
+                        .getResourceAsStream(classpathStaticResource(path));
+        if (resource == null) {
+            return;
+        }
+
+        ctx.status(200);
+        ctx.header("Cache-Control", "max-age=0");
+        String contentType = contentTypeFor(path);
+        if (contentType != null) {
+            ctx.contentType(contentType);
+        }
+        if (ctx.method() == HandlerType.HEAD) {
+            resource.close();
+            ctx.result(new byte[0]);
+        } else {
+            ctx.result(resource);
+        }
+        ctx.skipRemainingHandlers();
+    }
+
+    private boolean isStaticAssetPath(final String path) {
+        for (String prefix : STATIC_ASSET_PREFIXES) {
+            if (path.startsWith(prefix)) {
+                return true;
+            }
+        }
+        for (String file : STATIC_ASSET_FILES) {
+            if (path.equals(file)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private String classpathStaticResource(final String path) {
+        String base = staticFilePath == null ? "" : staticFilePath.trim();
+        while (base.startsWith("/")) {
+            base = base.substring(1);
+        }
+        while (base.endsWith("/")) {
+            base = base.substring(0, base.length() - 1);
+        }
+        String resourcePath = path.startsWith("/") ? path.substring(1) : path;
+        if (base.isEmpty()) {
+            return resourcePath;
+        }
+        return base + "/" + resourcePath;
+    }
+
+    private String contentTypeFor(final String path) {
+        if (path.endsWith(".css")) {
+            return "text/css";
+        }
+        if (path.endsWith(".js")) {
+            return "application/javascript";
+        }
+        if (path.endsWith(".webmanifest")) {
+            return "application/manifest+json";
+        }
+        if (path.endsWith(".png")) {
+            return "image/png";
+        }
+        if (path.endsWith(".ico")) {
+            return "image/x-icon";
+        }
+        if (path.endsWith(".svg")) {
+            return "image/svg+xml";
+        }
+        if (path.endsWith(".txt")) {
+            return "text/plain";
+        }
+        return URLConnection.guessContentTypeFromName(path);
+    }
+
     public void stop() {
         if (app != null) {
             app.stop();
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGenerator.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGenerator.java
index 7480ce86..6087f026 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGenerator.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGenerator.java
@@ -438,6 +438,7 @@ public String getApiDocumentation(
             }
         }
 
+        output.append(paragraph(href("Open Swagger UI", prependPath + "/docs/swagger-ui")));
         output.append(
                 paragraph(href("[download normal swagger file]", prependPath + "/docs/swagger")));
         output.append(
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerUiPage.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerUiPage.java
new file mode 100644
index 00000000..d74f6501
--- /dev/null
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerUiPage.java
@@ -0,0 +1,176 @@
+package uk.co.compendiumdev.thingifier.swaggerizer;
+
+import uk.co.compendiumdev.thingifier.Thingifier;
+import uk.co.compendiumdev.thingifier.api.docgen.ThingifierApiDocumentationDefn;
+import uk.co.compendiumdev.thingifier.htmlgui.htmlgen.DefaultGUIHTML;
+
+public final class SwaggerUiPage {
+
+    private static final String SWAGGER_UI_CSS = "https://unpkg.com/swagger-ui-dist/swagger-ui.css";
+    private static final String SWAGGER_UI_BUNDLE =
+            "https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js";
+    private static final String SWAGGER_UI_PRESET =
+            "https://unpkg.com/swagger-ui-dist/swagger-ui-standalone-preset.js";
+
+    private final ThingifierApiDocumentationDefn apiDefn;
+    private final DefaultGUIHTML guiManagement;
+    private final String openApiUrl;
+    private final String docsUrl;
+    private final String downloadUrl;
+    private final String canonicalUrl;
+
+    public SwaggerUiPage(
+            final ThingifierApiDocumentationDefn apiDefn,
+            final DefaultGUIHTML guiManagement,
+            final String openApiUrl,
+            final String docsUrl,
+            final String downloadUrl,
+            final String canonicalUrl) {
+        this.apiDefn = apiDefn;
+        this.guiManagement = guiManagement;
+        this.openApiUrl = openApiUrl;
+        this.docsUrl = docsUrl;
+        this.downloadUrl = downloadUrl;
+        this.canonicalUrl = canonicalUrl;
+    }
+
+    public String html() {
+        final String title = resolveTitle();
+        final StringBuilder html = new StringBuilder();
+
+        html.append(guiManagement.getPageStart(title, headInject(), canonicalUrl));
+        html.append(guiManagement.getMenuAsHTML());
+        html.append(guiManagement.getStartOfMainContentMarker());
+        html.append("<div class='swagger-ui-page'>");
+        html.append("<h1>").append(escapeHtml(title)).append("</h1>");
+        html.append("<p>");
+        html.append("<a href='").append(escapeHtmlAttribute(docsUrl)).append("'>API Docs</a>");
+        html.append(" | ");
+        html.append("<a href='")
+                .append(escapeHtmlAttribute(downloadUrl))
+                .append("'>Download OpenAPI JSON</a>");
+        html.append("</p>");
+        html.append("<div id='swagger-ui'></div>");
+        html.append("<script src='")
+                .append(SWAGGER_UI_BUNDLE)
+                .append("' charset='UTF-8'></script>");
+        html.append("<script src='")
+                .append(SWAGGER_UI_PRESET)
+                .append("' charset='UTF-8'></script>");
+        html.append("<script>");
+        html.append("window.onload = function () {");
+        html.append("document.documentElement.classList.remove(\"dark-mode\");");
+        html.append("window.ui = SwaggerUIBundle({");
+        html.append("url: \"").append(escapeJavaScriptString(openApiUrl)).append("\",");
+        html.append("dom_id: \"#swagger-ui\",");
+        html.append("deepLinking: true,");
+        html.append("syntaxHighlight: {activated: false},");
+        html.append("presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],");
+        html.append("plugins: [SwaggerUIBundle.plugins.DownloadUrl],");
+        html.append("layout: \"StandaloneLayout\"");
+        html.append("});");
+        html.append("setTimeout(function () {");
+        html.append("document.documentElement.classList.remove(\"dark-mode\");");
+        html.append("}, 0);");
+        html.append("};");
+        html.append("</script>");
+        html.append("</div>");
+        html.append(guiManagement.getEndOfMainContentMarker());
+        html.append(guiManagement.getPageFooter());
+        html.append(guiManagement.getPageEnd());
+        return html.toString();
+    }
+
+    private String headInject() {
+        return "<link rel='stylesheet' href='"
+                + SWAGGER_UI_CSS
+                + "'>"
+                + "<style>"
+                + lightThemeCss()
+                + "</style>";
+    }
+
+    private String lightThemeCss() {
+        return String.join(
+                "",
+                "html{background:#fff;}",
+                ".swagger-ui-page{background:#fff;color:#222;color-scheme:light;}",
+                ".swagger-ui-page h1{margin-bottom:.25em;}",
+                ".swagger-ui-page #swagger-ui{margin-top:1em;}",
+                ".swagger-ui{background:#fff;color:#222;color-scheme:light;}",
+                ".swagger-ui .topbar{display:none;}",
+                ".swagger-ui .wrapper,.swagger-ui .scheme-container,"
+                        + ".swagger-ui section.models,.swagger-ui .model-box,"
+                        + ".swagger-ui .opblock,.swagger-ui .opblock .opblock-summary,"
+                        + ".swagger-ui .opblock .opblock-section-header,"
+                        + ".swagger-ui .responses-inner,.swagger-ui table,"
+                        + ".swagger-ui .dialog-ux .modal-ux{background:#fff!important;"
+                        + "color:#222!important;}",
+                ".swagger-ui .scheme-container{box-shadow:none!important;"
+                        + "border:1px solid #d7d7d7;}",
+                ".swagger-ui .opblock .opblock-section-header{box-shadow:none!important;"
+                        + "border-bottom:1px solid #d7d7d7;}",
+                ".swagger-ui .info .title,.swagger-ui .opblock-tag,"
+                        + ".swagger-ui .opblock-summary-description,"
+                        + ".swagger-ui .markdown p,.swagger-ui .markdown li,"
+                        + ".swagger-ui .renderedMarkdown p,.swagger-ui .renderedMarkdown li,"
+                        + ".swagger-ui table thead tr td,.swagger-ui table thead tr th,"
+                        + ".swagger-ui table tbody tr td,.swagger-ui label,"
+                        + ".swagger-ui .parameter__name,.swagger-ui .parameter__type,"
+                        + ".swagger-ui .response-col_status,.swagger-ui .response-col_description,"
+                        + ".swagger-ui .model-title,.swagger-ui .model{color:#222!important;}",
+                ".swagger-ui a,.swagger-ui .link,.swagger-ui .opblock-tag:hover{"
+                        + "color:#1f5f8b!important;}",
+                ".swagger-ui input,.swagger-ui textarea,.swagger-ui select{background:#fff!important;"
+                        + "color:#222!important;border-color:#8b8b8b!important;}",
+                ".swagger-ui .btn,.swagger-ui button{background:#fff!important;"
+                        + "color:#222!important;border-color:#777!important;}",
+                ".swagger-ui .highlight-code,.swagger-ui .microlight{background:#f7f7f7!important;"
+                        + "color:#222!important;}");
+    }
+
+    private String resolveTitle() {
+        final String configuredTitle = firstNonBlank(apiDefn.getSeoTitle(), apiDefn.getTitle());
+        if (!configuredTitle.isEmpty()) {
+            return configuredTitle + " Swagger UI";
+        }
+        final Thingifier thingifier = apiDefn.getThingifier();
+        if (thingifier != null
+                && thingifier.getTitle() != null
+                && !thingifier.getTitle().trim().isEmpty()) {
+            return thingifier.getTitle().trim() + " Swagger UI";
+        }
+        return "API Swagger UI";
+    }
+
+    private String firstNonBlank(final String preferred, final String fallback) {
+        if (preferred != null && !preferred.trim().isEmpty()) {
+            return preferred.trim();
+        }
+        if (fallback != null && !fallback.trim().isEmpty()) {
+            return fallback.trim();
+        }
+        return "";
+    }
+
+    private String escapeHtml(final String value) {
+        if (value == null) {
+            return "";
+        }
+        return value.replace("&", "&amp;")
+                .replace("<", "&lt;")
+                .replace(">", "&gt;")
+                .replace("\"", "&quot;");
+    }
+
+    private String escapeHtmlAttribute(final String value) {
+        return escapeHtml(value).replace("'", "&#39;");
+    }
+
+    private String escapeJavaScriptString(final String value) {
+        if (value == null) {
+            return "";
+        }
+        return value.replace("\\", "\\\\").replace("\"", "\\\"");
+    }
+}
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/Swaggerizer.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/Swaggerizer.java
index b832b0b0..6c552f02 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/Swaggerizer.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/Swaggerizer.java
@@ -511,6 +511,17 @@ public String asJson() {
         return asJson(false);
     }
 
+    public String asJsonWithPreferredServer(final String preferredServerUrl) {
+        return asJsonWithPreferredServer(false, preferredServerUrl);
+    }
+
+    public String asJsonWithPreferredServer(
+            final boolean permissive, final String preferredServerUrl) {
+        final OpenAPI api = permissive ? swaggerPermissive() : swagger();
+        preferServer(api, preferredServerUrl);
+        return Json31.pretty(api);
+    }
+
     public String asJson(boolean permissive) {
         if (apiNormal == null) {
             apiNormal = swagger();
@@ -524,4 +535,45 @@ public String asJson(boolean permissive) {
             return Json31.pretty(apiNormal);
         }
     }
+
+    private void preferServer(final OpenAPI api, final String preferredServerUrl) {
+        if (preferredServerUrl == null || preferredServerUrl.trim().isEmpty()) {
+            return;
+        }
+
+        final String preferredUrl = preferredServerUrl.trim();
+        final List<Server> existingServers = api.getServers();
+        final List<Server> reorderedServers = new ArrayList<>();
+        Server preferredServer = null;
+
+        if (existingServers != null) {
+            for (Server server : existingServers) {
+                if (sameServerUrl(preferredUrl, server.getUrl())) {
+                    preferredServer = server;
+                } else {
+                    reorderedServers.add(server);
+                }
+            }
+        }
+
+        if (preferredServer == null) {
+            preferredServer = new Server().description("current request").url(preferredUrl);
+        }
+        reorderedServers.add(0, preferredServer);
+        api.setServers(reorderedServers);
+    }
+
+    private boolean sameServerUrl(final String preferredUrl, final String configuredUrl) {
+        if (configuredUrl == null) {
+            return false;
+        }
+        return removeTrailingSlash(preferredUrl).equals(removeTrailingSlash(configuredUrl.trim()));
+    }
+
+    private String removeTrailingSlash(final String url) {
+        if (url.endsWith("/")) {
+            return url.substring(0, url.length() - 1);
+        }
+        return url;
+    }
 }