Swagger UI renders OpenAPI specs as interactive documentation

Swagger UI turns specs into interactive API docs

Swagger UI is a tool that lets anyone, from a development team to end consumers, visualize and interact with an API's resources without having any of the implementation logic in place. It is generated automatically from an OpenAPI Specification, previously known as the Swagger Specification, and the visual documentation supports both back end implementation and client side consumption.

Because it reads a specification rather than a live server, the interface can present endpoints, parameters, and schemas in one place and let users send requests directly from the browser. That separation is what makes the same document useful to a back end engineer implementing the contract and to a front end consumer who only needs to know how to call it.

Three npm modules for different setups

The repository publishes three separate npm modules. swagger-ui is the traditional module intended for single-page applications that can resolve dependencies through tools like Webpack or Browserify. swagger-ui-dist is a dependency-free module that includes everything needed to serve Swagger UI in a server-side project or in a single-page application that cannot resolve npm dependencies.

swagger-ui-react packages Swagger UI as a React component for use in React applications. The README strongly suggests using swagger-ui instead of swagger-ui-dist for single-page applications because swagger-ui-dist is significantly larger. For plain HTML, JS, and CSS, the guidance is to download the latest release and copy the contents of the dist folder to a server.

The README also points users who want an older experience to the 2.x branch, which remains available for projects that have not moved to the current major version. Picking the right module avoids shipping the much larger dependency-free build into an application that can already resolve npm packages.

OpenAPI Specification compatibility across versions

The OpenAPI Specification has gone through five revisions since its creation in 2010, and Swagger UI tracks them with a long compatibility table. The newest entry, version 5.32.0 released on 2026-02-27, supports OpenAPI 2.0 and the 3.0.0 through 3.2.0 line. Version 5.19.0 from 2025-02-17 supports up to 3.1.2, and version 5.0.0 from 2023-06-12 supports up to 3.1.0.

Older releases remain documented for users on legacy stacks: 4.0.0 from 2021 covers up to 3.0.3, 3.18.3 from 2018 the same, and the 2.x and 1.x lines cover progressively earlier specification versions. This table lets teams pick a Swagger UI release that matches the specification their API declares.

Anonymized install analytics and how to opt out

Swagger UI uses Scarf to collect anonymized installation analytics. The README states these analytics help support the maintainers and only run during installation, not at runtime.

To opt out, set the scarfSettings.enabled field to false in the project's package.json, or set the SCARF_ANALYTICS environment variable to false in the environment that installs the packages, for example by running SCARF_ANALYTICS=false npm install. The package.json form looks like this:

// package.json
{
  // ...
  "scarfSettings": {
    "enabled": false
  }
  // ...
}

Documentation, customization, and plugin APIs

The project organizes its docs into several groups. The Usage section covers installation, configuration, CORS, OAuth2, deep linking, limitations, and version detection. The Customization section covers an overview, the plugin API, and building a custom layout. A Development section covers setting up and available scripts, and a Contributing section points to the shared swagger-api contributing guide.

This structure means a team can adopt Swagger UI with a basic install, then extend it through the plugin API and custom layouts as needs grow, rather than forking the tool. The same docs also note a Good First Issue label for contributors looking for an approachable entry point into the codebase.

End-to-end testing with Cypress

Swagger UI's integration tests are end-to-end checks built on Cypress. The full suite can be run locally with a single command that starts the required servers, runs Cypress headless, and shuts the servers down afterwards. There is also an interactive mode that opens the Cypress runner for debugging individual specs.

Running one spec headlessly is a two-terminal affair: a cy:start script brings up the servers in the first terminal, and a cy:run script with the --spec flag targets a single feature file from the second. The README warns against running a dev server on the same ports while testing, because the test runner manages its own servers.

Known issues, browser support, and licensing

The README lists known issues that remain with the 3.X line. Only part of the previously supported parameters are available, the JSON Form Editor is not implemented, support for collectionFormat is partial, localization through translations is not implemented, and relative path support for external files is not implemented.

Swagger UI works in the latest versions of Chrome, Safari, Firefox, and Edge. For security issues, the project asks reporters to email [email protected] rather than use the public issue tracker. The tool is licensed under the Apache 2.0 license and ships with an explicit NOTICE file containing additional legal notices.

The NOTICE file is called out separately from the license because it carries attributions and notices that downstream redistributors must preserve. Together the Apache 2.0 license and the NOTICE file define what users may do when they embed or redistribute Swagger UI.

Editorial conclusion

Swagger UI converts an OpenAPI Specification into a live, interactive document that developers and consumers can use to explore and call an API without standing up the implementation. It ships as three npm modules plus a plain HTML build, tracks OpenAPI revisions from the 1.x era through the 3.2.0 line, and supports extension through a plugin API and custom layouts. With documented Cypress tests, clear opt-out analytics, and an Apache 2.0 license, it remains a standard choice for API documentation.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. swagger-api/swagger-ui on GitHub