swagger-ui-express

swagger-ui-express is a small piece of Express middleware that renders the Swagger UI single-page app inside your own server, bound to a Swagger/OpenAPI document you supply. Instead of hosting a separate static docs site, you mount it on a route (commonly /api-docs) and it serves the same interactive, explorable documentation UI that swagger.io uses, styled and driven by whatever spec your app produces.

The spec can come from a static JSON file, a dynamically generated object (for example from swagger-jsdoc), a remote URL, or even be computed per-request by attaching it to req.swaggerDoc. The library ships extensive customization hooks — custom CSS (inline or via URL), custom JavaScript (inline or via URL), custom page titles, favicon overrides, robots meta tags, and OAuth/API-key preauthorization — so the hosted docs page can be made to match a product’s branding rather than looking like generic tooling.

Because the actual rendering is handled by the versioned swagger-ui-dist package, swagger-ui-express stays a thin, focused wrapper: its job is templating the HTML shell, serving the static Swagger UI assets, and wiring options through to the client-side SwaggerUIBundle call. This keeps the middleware itself tiny while still exposing nearly all of Swagger UI’s underlying configuration surface to Express developers.

What You Get

• serve + setup(swaggerDoc, opts) middleware pair to mount interactive API docs on any Express route
• Support for static JSON specs, dynamically generated specs (e.g. from swagger-jsdoc), or specs loaded from a remote URL
• Per-request spec support via req.swaggerDoc, so different documentation can be served to different callers
• Custom CSS, custom JS (inline or external URL), custom page title, and custom favicon options for branding the docs page
• A dropdown “explorer” mode for switching between multiple Swagger documents from one page
• OAuth and API-key preauthorization hooks (customOptions.oauth, customOptions.preauthorizeApiKey) so testers don’t have to manually authenticate every session
• serveFiles/serveWithOptions variants for hosting two or more independent Swagger UI instances from the same app

Common Use Cases

• Hosting living API documentation for an Express-based REST API directly from the same process that serves the API
• Pairing with swagger-jsdoc to generate the OpenAPI spec from JSDoc comments and immediately render it as browsable docs
• Exposing a /api-docs endpoint internal teams and API consumers can use to try requests via the built-in “Authorize” and “Try it out” UI
• Serving two versions of an API (e.g. /v1/api-docs and /v2/api-docs) with distinct Swagger documents via serveFiles
• Preauthorizing a documentation page with an API key or OAuth token so internal reviewers don’t re-enter credentials

Under The Hood

Architecture The module is a single index.js file built around one core function, generateHTML, which takes a Swagger document plus an options bag and does pure string templating: it substitutes placeholders (<% customCss %>, <% favIconString %>, <% title %>, and so on) into an HTML template string and a companion JS template string that ultimately calls SwaggerUIBundle in the browser. setup() wraps this in an Express handler that re-renders per-request when req.swaggerDoc is present (letting different requests see different specs), while serve/serveFiles compose that handler with express.static pointed at swagger-ui-dist’s asset directory (getAbsoluteSwaggerFsPath()). There is no class hierarchy, router, or plugin system — the entire surface area is a handful of exported functions operating on plain objects, which keeps the blast radius of a spec/options change limited to the templating layer itself.

Tech Stack The library targets Node’s CommonJS module system and Express (>=4.0.0 as a peer dependency, with 5.x beta also declared compatible), with swagger-ui-dist as its one runtime dependency for the actual Swagger UI static bundle. Development tooling is Mocha for the test runner, nyc/istanbul-badges-readme for coverage, and Puppeteer to drive a real headless Chromium instance against a small Express testapp fixture for integration-style assertions rather than mocking the browser layer. CI is configured via a legacy .travis.yml targeting Node 8 and 10, which is older than the package’s stated >= v0.10.32 engines field and likely predates the project’s more recent 5.x releases.

Code Quality Testing is integration-first: test/test.spec.js boots a real Express server backed by test/testapp/app.js, launches Puppeteer, and asserts against rendered DOM selectors (.information-container, .swagger-ui, auth-button lock state) rather than unit-testing generateHTML in isolation. This gives strong end-to-end confidence that the shipped HTML/JS actually renders correctly in a browser, at some cost to fast, isolated coverage of individual option combinations. The source itself uses plain var declarations, informal legacy-JS style (matching its 2016 origins), and no TypeScript types; error handling is minimal since the module does no I/O beyond serving static files and templating strings, so there is little that can throw at runtime. There is no linter configuration in the repo.

API Design The public API is small and pragmatic: serve + setup(doc, opts) covers the common case in two lines, while power users reach for serveFiles, serveWithOptions, or generateHTML directly for multi-spec or fully custom setups. Options are a single flat object (explorer, customCss, customJs, swaggerOptions, customSiteTitle, etc.) documented thoroughly in the README with runnable examples for every variant, which keeps the learning curve low even though the options surface itself is fairly large. The one legacy wrinkle is setup’s positional-arguments overload (opts, options, customCss, customfavIcon, swaggerUrl, customSiteTitle as separate parameters) kept alongside the newer single-options-object form for backward compatibility, which is undocumented as deprecated but still present in the function signature.