feat(openapi): add swagger ui config (#4185)

OskarLebuda · RihanArfan · commit ff18934e8e24 · 2026-04-13T14:21:20.000+01:00
diff --git a/docs/3.config/0.index.md b/docs/3.config/0.index.md
@@ -207,6 +207,21 @@ openAPI: {
 }
 ```
 
+If you like to customize the Swagger UI, you can pass any [Swagger UI configuration option](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/):
+
+```js
+openAPI: {
+  ui: {
+    swagger: {
+      persistAuthorization: true,
+      deepLinking: true,
+      docExpansion: 'none',
+      filter: true,
+    }
+  }
+}
+```
+
 Or if you want to customize the endpoints:
 
 ```js
diff --git a/src/runtime/internal/routes/swagger.ts b/src/runtime/internal/routes/swagger.ts
@@ -10,6 +10,11 @@ export default defineHandler((event) => {
   const description = runtimeConfig.nitro?.openAPI?.meta?.description || "";
   const openAPIEndpoint = runtimeConfig.nitro?.openAPI?.route || "./_openapi.json";
 
+  const { route: _route, ...swaggerConfig } =
+    (runtimeConfig.nitro?.openAPI?.ui?.swagger as Record<string, unknown>) || {};
+
+  const safeSwaggerConfig = JSON.stringify(swaggerConfig).replace(/<\//g, "<\\/");
+
   const CDN_BASE = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@^5";
   event.res.headers.set("Content-Type", "text/html");
   return /* html */ `<!doctype html>
@@ -31,13 +36,14 @@ export default defineHandler((event) => {
         <script>
           window.onload = () => {
             window.ui = SwaggerUIBundle({
-              url: ${JSON.stringify(openAPIEndpoint)},
-              dom_id: "#swagger-ui",
               presets: [
                 SwaggerUIBundle.presets.apis,
                 SwaggerUIStandalonePreset,
               ],
-              layout2: "StandaloneLayout",
+              layout: "StandaloneLayout",
+              ...${safeSwaggerConfig},
+              url: ${JSON.stringify(openAPIEndpoint)},
+              dom_id: "#swagger-ui",
             });
           };
         </script>
diff --git a/src/types/openapi.ts b/src/types/openapi.ts
@@ -1,5 +1,36 @@
 // import type { ApiReferenceConfiguration as ScalarConfig } from "@scalar/api-reference";
 
+/**
+ * Swagger UI configuration options.
+ *
+ * @see https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
+ */
+export interface SwaggerUIConfig {
+  deepLinking?: boolean;
+  displayOperationId?: boolean;
+  defaultModelsExpandDepth?: number;
+  defaultModelExpandDepth?: number;
+  defaultModelRendering?: "example" | "model";
+  displayRequestDuration?: boolean;
+  docExpansion?: "list" | "full" | "none";
+  filter?: boolean | string;
+  persistAuthorization?: boolean;
+  requestSnippetsEnabled?: boolean;
+  showExtensions?: boolean;
+  showCommonExtensions?: boolean;
+  /** Only "alpha" is supported (function values are not JSON-serializable). */
+  tagsSorter?: "alpha";
+  /**
+   * Note: function callbacks cannot be passed via Nitro configuration (not JSON-serializable).
+   */
+  onComplete?: never;
+  layout?: string;
+  configUrl?: string;
+  oauth2RedirectUrl?: string;
+  withCredentials?: boolean;
+  [key: string]: unknown;
+}
+
 /**
  * Nitro OpenAPI configuration.
  *
@@ -57,16 +88,18 @@ export interface NitroOpenAPIConfig {
      * Swagger UI configuration.
      *
      * Set to `false` to disable.
+     *
+     * @see https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
      */
     swagger?:
       | false
-      | {
+      | (SwaggerUIConfig & {
           /**
            * Route for Swagger UI.
            *
            * @default "/_swagger"
            */
           route?: string;
-        };
+        });
   };
 }
