feat(openapi): add swagger ui config

[OskarLebuda]

🔗 Linked issue

Resolves #3959

❓ Type of change

• 📖 Documentation (updates to the documentation, readme, or JSdoc annotations)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[vercel]

@OskarLebuda is attempting to deploy a commit to the Nitro Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds typed Swagger UI options, applies them at runtime by merging into SwaggerUIBundle initialization, and documents how to configure these options via openAPI.ui.swagger.

Changes

Cohort / File(s)	Summary
Documentation docs/3.config/0.index.md	Inserted a new section demonstrating how to configure Swagger UI via openAPI.ui.swagger (examples: persistAuthorization, deepLinking, docExpansion, filter).
Type Definitions src/types/openapi.ts	Added exported SwaggerUIConfig interface with typed Swagger UI options and updated NitroOpenAPIConfig.ui.swagger to accept `false
Runtime Handler src/runtime/internal/routes/swagger.ts	Handler now destructures runtimeConfig.nitro.openAPI.ui.swagger, escapes and serializes the config, spreads it into SwaggerUIBundle init, and replaced layout2 with layout in options.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description is related to the changeset, linking issue #3959 and indicating documentation updates for Swagger UI configuration support.
Linked Issues check	✅ Passed	The PR fully addresses issue #3959 by exposing Swagger UI configuration parameters through typed support in NitroOpenAPIConfig [#3959].
Out of Scope Changes check	✅ Passed	All changes directly support the objective of adding Swagger UI configuration: documentation, type definitions, and runtime handler modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title follows conventional commits format with 'feat' type and 'openapi' scope, clearly describing the main feature addition of Swagger UI configuration support.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/runtime/internal/routes/swagger.ts (1)

41-44: Consider escaping JSON output to prevent HTML breakage.

If any swaggerConfig value contains </script>, it will break the HTML structure. While this is developer-controlled config (not user input), it's a defensive improvement.

♻️ Proposed fix to safely embed JSON in script tag

         <script>
           window.onload = () => {
             window.ui = SwaggerUIBundle({
               presets: [
                 SwaggerUIBundle.presets.apis,
                 SwaggerUIStandalonePreset,
               ],
               layout: "StandaloneLayout",
-              ...${JSON.stringify(swaggerConfig)},
+              ...${JSON.stringify(swaggerConfig).replace(/</g, "\\u003c")},
               url: ${JSON.stringify(openAPIEndpoint)},
               dom_id: "#swagger-ui",
             });
           };
         </script>

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/runtime/internal/routes/swagger.ts` around lines 41 - 44, The embedded
JSON for swaggerConfig and openAPIEndpoint in the template (the
...${JSON.stringify(swaggerConfig)} and url: ${JSON.stringify(openAPIEndpoint)}
spots in routes/swagger.ts) must be escaped to prevent breaking the surrounding
<script> if any value contains </script>; update the code to serialize and then
sanitize the JSON (e.g., pass JSON.stringify(swaggerConfig) and
JSON.stringify(openAPIEndpoint) through a small helper like escapeForScript that
replaces "</script>" with "<\\/script>" (and other minimal safe replacements
such as "</!--" if desired) before embedding, or use a safe serializer utility,
and reference that sanitized string in the template instead of raw
JSON.stringify output.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/types/openapi.ts`:
- Around line 21-22: The interface currently allows function values for
tagsSorter and onComplete but swagger.ts serializes config with JSON.stringify
which drops functions; update the src/types/openapi.ts declarations for
tagsSorter and onComplete to remove/function types and add a clear JSDoc note
above each property (tagsSorter and onComplete) stating that function callbacks
are not supported at runtime because the config is JSON-serialized in swagger.ts
and will be ignored, and advise the supported alternatives (e.g., use "alpha" or
external wiring for lifecycle hooks).

---

Nitpick comments:
In `@src/runtime/internal/routes/swagger.ts`:
- Around line 41-44: The embedded JSON for swaggerConfig and openAPIEndpoint in
the template (the ...${JSON.stringify(swaggerConfig)} and url:
${JSON.stringify(openAPIEndpoint)} spots in routes/swagger.ts) must be escaped
to prevent breaking the surrounding <script> if any value contains </script>;
update the code to serialize and then sanitize the JSON (e.g., pass
JSON.stringify(swaggerConfig) and JSON.stringify(openAPIEndpoint) through a
small helper like escapeForScript that replaces "</script>" with "<\\/script>"
(and other minimal safe replacements such as "</!--" if desired) before
embedding, or use a safe serializer utility, and reference that sanitized string
in the template instead of raw JSON.stringify output.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1485defa-5a69-4e14-b471-908b5728692c

📥 Commits

Reviewing files that changed from the base of the PR and between a5a3389 and 032dfd4.

📒 Files selected for processing (3)

• docs/3.config/0.index.md
• src/runtime/internal/routes/swagger.ts
• src/types/openapi.ts

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/nitro@4185

commit: 5d75be5

[pi0]

Thanks! ❤️

We need to refactor this once refactoring to https://github.com/unjs/openapi-renderer

[OskarLebuda]

Thanks! ❤️

We need to refactor this once refactoring to https://github.com/unjs/openapi-renderer

I've got this on my TODO list. PR will be ready soon 🚀