Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here

swagger-ui

Swagger UI is a collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.

Subscribe to updates I use swagger-ui


Statistics on swagger-ui

Number of watchers on Github 10876
Number of open issues 214
Average time to close an issue 4 days
Main language JavaScript
Average time to merge a PR 2 days
Open pull requests 155+
Closed pull requests 78+
Last commit over 1 year ago
Repo Created about 8 years ago
Repo Last Updated over 1 year ago
Size 197 MB
Homepage http://swagger.io
Organization / Authorswagger-api
Latest Releasev3.12.1
Contributors126
Page Updated
Do you use swagger-ui? Leave a review!
View open issues (214)
View swagger-ui activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating swagger-ui for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

Swagger UI

NPM version

New!

This is the new version of swagger-ui, 3.x. Want to learn more? Check out our FAQ.

** Want to score an easy open-source contribution?** Check out our Good first issue label.

As a brand new version, written from the ground up, there are some known issues and unimplemented features. Check out the Known Issues section for more details.

This repository publishes to two different NPM modules:

  • swagger-ui is a traditional npm module intended for use in JavaScript web application projects that are capable of resolving dependencies (via Webpack, Browserify, etc).
  • swagger-ui-dist is a dependency-free module that includes everything you need to serve Swagger-UI in a server-side project, or a web project that can't resolve npm module dependencies.

For the older version of swagger-ui, refer to the 2.x branch.

Compatibility

The OpenAPI Specification has undergone 5 revisions since initial creation in 2010. Compatibility between swagger-ui and the OpenAPI Specification is as follows:

Swagger UI Version Release Date OpenAPI Spec compatibility Notes
3.12.1 2018-03-09 2.0, 3.0 tag v3.12.1
3.0.21 2017-07-26 2.0 tag v3.0.21
2.2.10 2017-01-04 1.1, 1.2, 2.0 tag v2.2.10
2.1.5 2016-07-20 1.1, 1.2, 2.0 tag v2.1.5
2.0.24 2014-09-12 1.1, 1.2 tag v2.0.24
1.0.13 2013-03-08 1.1, 1.2 tag v1.0.13
1.0.1 2011-10-11 1.0, 1.1 tag v1.0.1

Documentation

Usage

Customization

Development

Integration Tests

You will need JDK of version 7 or higher as instructed here http://nightwatchjs.org/gettingstarted#selenium-server-setup

Integration tests can be run locally with npm run e2e - be sure you aren't running a dev server when testing!

Browser support

Swagger UI works in the latest versions of Chrome, Safari, Firefox, Edge and IE11.

Known Issues

To help with the migration, here are the currently known issues with 3.X. This list will update regularly, and will not include features that were not implemented in previous versions.

  • Only part of the parameters previously supported are available.
  • The JSON Form Editor is not implemented.
  • Support for collectionFormat is partial.
  • l10n (translations) is not implemented.
  • Relative path support for external files is not implemented.

Security contact

Please disclose any security-related issues or vulnerabilities by emailing security@swagger.io, instead of using the public issue tracker.

License

Copyright 2017 SmartBear Software

Licensed under the Apache License, Version 2.0 (the License); you may not use this file except in compliance with the License. You may obtain a copy of the License at apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

swagger-ui open issues Ask a question     (View All Issues)
  • almost 3 years type dateTime does not render in Example Value without a provided default
  • almost 3 years How to insert linebreak in Swagger v2.2.3
  • almost 3 years [improvement] Translation: automatic and manual language selection
  • almost 3 years Test UI does not send HTTP GET body
  • almost 3 years OAuth2 request adds `vendorExtension` scope to all auth requests
  • almost 3 years Description text is incorrectly escaped
  • almost 3 years Hide ModelBinder paramter from Swagger UI. ASP.NET C#
  • almost 3 years Swagger UI stripping HTML
  • almost 3 years Response Messages (Response Model) failing for application/xml
  • almost 3 years when i send the type of Long param to request server, the request was failed
  • almost 3 years Exceptions when request and response contain image file
  • almost 3 years Model / Example displays locally but not served via S3
  • almost 3 years Make `Response Messages` section collapsable
  • almost 3 years How to display the GET request Response body, Response Code and Response Headers on Swagger UI?
  • almost 3 years No error in UI when required file param is not provided
  • almost 3 years Array not working
  • almost 3 years Basic Auth is broken when using non-ASCII characters
  • almost 3 years Swager-UI Server doesn't consume application/json, try [ ]
  • almost 3 years Authorize: Markdown not being translated
  • almost 3 years Request header always shows json content type
  • almost 3 years JSON object into enum - different keys and values
  • almost 3 years Response Message's Example Value not shown
  • almost 3 years Discriminator does not switch schema
  • almost 3 years Model rendering does not respect minimum value
  • almost 3 years Posting an associative array alongside with formdata doest work
  • almost 3 years Swagger UI does not display response models properly
  • almost 3 years Using allof in an array in response body generates blank examples
  • almost 3 years Enhancing $ref to point to sub elements of a model
  • almost 3 years Download file broken since 2.2.3
  • almost 3 years UI omits the accept (Response Content Type) dropdown for non-JSON response
swagger-ui open pull requests (View All Pulls)
  • Upgraded highlight version to 9.1, removed highlight when sample is t…
  • Minor safety check
  • fixes #1186 Render primitive types in "Response Class"
  • fix issue #1475
  • add badges for PR and issue stats
  • added safe name handling
  • Extract inline JS initialization logic and add a CSP <meta> tag to kill XSS
  • update index.html
  • Added support for oauth2-password-flow (refactored #1574)
  • replaced broken font file
  • Fix converting basicAuth authorization from 1.2 to 2.0 schema version
  • Fix toggling of the basic authentication form
  • Separate config from index.html into config.js
  • SPDX bower compatibility
  • Respect the name of the api key supplied in spec
  • Added scheme and host parameters in url to override configuration.
  • Render image/svg+xml responses as an image
  • Error Checking Improvement and Performance Improvement
  • Adding a Modal Panel to set global API_KEY
  • Don't dereference param.type if undefined
  • fix how default url is loaded from window.location
  • Changes to support swagger 1.2
  • Fix calculation of operation "number" property
  • Simplify online validator URL building (HTTP[S]?)
  • fix some XSS with improved handlebar template escaping
  • Markdown fixes
  • [WIP, review needed] refactor parameter validation + check validity of JSON
  • Markdown rendered tag descriptions.
  • Will show headers on response messages
  • Adjust curl output
  • rebuild, updated swagger-js to 2.1.12
  • Fix for #2004
  • url decode paths before expanding
  • Fix slowness of ui render
  • Added debug task to gulpfile and removed dist from versioning
  • Fixing case where there is no parameter type
  • HTML5 pattern validation
  • fixes #2043 Switch Authorize and Explore buttons
  • Fixed buildUrl to handle relative paths correctly
  • make URLs/links clickable in JSON responses
  • Allow `ctrl + enter` pressed to make multiline
  • Fix Issue #2075
  • slimmed Docker image + usage
  • BUGFIX: url input name doesn't match query parameter.
  • Oauth2 scope fixes
  • Added search
  • Add production Dockerfile
  • fix validator pop views
  • Make optional oauth parameter
  • Don't require a password
  • Remove unnecessary class from main.handlebars template
  • Fix #1350 - oauth2 redirect url correctly used
  • fix tests
  • rebuilt
  • allow fetching local #/x- definitions for response headers
  • make redirect_uri global
  • Make oauth2 scopes optional
  • [#2167] fix xml generator break condition
  • specs.less refactoring: group .markdown styling together
  • Namespaces for arrays
  • Logout view didn't show username for basic authentication
  • fixes #2221
  • Created by translation is not working
  • Boolean param - swagger-ui.min.js
  • Support returning images and PDFs from POST requests.
  • validate integer inputs
  • if param.schema doesn't exist, then the line will fail
  • show operation id in operations heading
  • Set default oauth scope separator to whitespace
  • optimize png images using zopflipng
  • Update README.md - clarify Dockerfile location
  • Allow swaggerRequestHeaders as url parameter to index.html
  • Run Handlebars within Gulp instead of NPM
  • fix for xss issue
  • Added basic support for oauth2-password-flow
  • Make links contained in responses browsable [wip]
  • Fix escaping resource name when resource name has special characters in it.
  • load swagger json from inline spec
  • Set field minlength/maxlength based on model minLength/maxLength
  • Remove unnecessary executable permissions
  • Optimize PNGs with zopflipng -m (zopflipng 1.0.1)
  • support multiple swaggerUI / resource views on same page
  • for changes
  • Dynamic language selection.
  • Added support for passing through a basePath override.
  • When shebang contains parameters init inputs.
  • Feature: add responseHooks option for callbacks on responses
  • Implement OAuth2 password flow
  • Use filename from content-disposition in a download link
  • Use local reference to clientAuthorziations instead of global reference
  • Avoid using Facebook garbage fragment to complete login
  • Add tasks to gulpfile to minify all CSS and JS libs when building dist, removes 11000 lines from dist
  • Added meta tag to force IE11 to use edge document mode
  • Fix #2409: Not able to input the boolean array as one parameter
  • Fix #2369 - include js-yaml in index.html so string examples don't fail
  • Fix li.operation div.content overflow
  • Add the packaging metadata to build the swagger-ui snap
  • added max-width style to the parameter columns in the table
  • Validate server responses against the spec
  • Replace babel-polyfill with transform-runtime
  • fix(info): font for title, li and table
  • Make JSONEditor configurable
  • Fix code inside tables
  • Fixes issue #2711: <code> and <pre> are filtered from Swagger descriptions
  • Support enum values as property items type. Fixes #1381.
  • Leverage additionalQueryStringParams for flow === 'application' type
  • Use the selected content response type for curl command
  • cleaned up the presentation of the 'info' section (license, contact, externalDocs)
  • Fix #2652: Long URLs do not wrap properly
  • Fix #2648: Anchor links open a new tab/window
  • Fix #2647: <pre> tags in parameter descriptions are always 200px in height, regardless of their contents
  • Display response time
  • Make scope selected in auth view (controlled by flag)
  • generate handlerbars template as part of gulp build process
  • Improve large data set performance
  • Add translations for each Authorize tag in 2.x
  • update Docker base-image to alpine 3.5
  • New feature fix for array of objects in the definitions properties section
  • Removed ReadOnly properties from the JSON Parameters body example
  • Show actual error response when trying
  • add BASE_PATH in docker ENV
  • Force line endings of docker-run.sh to Unix-style
  • Fix 3859 Added support for oneOf and anyOf in array sample
  • initial perf, which gets stripped out in production
  • Fixes #4116 - uses mutated request for request URL in live-response.jsx.
  • Multiple examples
  • CI: Run e2e tests with CrossBrowserTesting
  • Update _table.scss to fix varying column widths
  • ESLint expansion
  • show oauth error callback message when auth fails
  • OAuth2 Owner Credentials flow now matches specification
  • Feature/docker volumes
  • OAS3 multi examples in requestbody
  • Add configuration to hide responses container
  • Read the x-example field and use them as values
  • Added support for '{realm}' placeholder in authorizationUrl and tokenUrl
  • Adds ability to set oauth2RedirectUrl using env vars for Docker
  • Basic Auth - OAuth Password Flow
  • Wrong usage of https://lodash.com/docs/4.17.5#lowerCase
  • Improve enum values for Enum Type in Swagger ReadOnly documentation
  • Add a button to reset example when user modifys request body
  • Fix deeplinking for topbar plugin
  • Fix(auth): improper resolution of relative token urls
  • Filter as a plugin
  • Add link to StackOverflow
  • Add option to show common query parameters
  • Add empty div if there are properties
  • Makes deep linking dynamic
  • fix: add client_id and client_secret to form when type is request-body
  • Add a "Close" button to the OAuth dialog, rename "Done" button elsewhere
  • Copy response to clipboard
  • Add isShown to ModelCollapse, to tie it to state
  • improve: show possible reasons when url fetch fails
  • Makes deep linking dynamic
  • OAuth2 Owner Credentials flow now matches specification
swagger-ui questions on Stackoverflow (View All Questions)
  • Swagger-ui basic authentication in local setup (locally hosted)
  • change swagger UI in wso2 api manager 1.9
  • swagger ui with collection (List) input parameter for Jax Rs resource
  • Swagger UI 2.1 Stuck "fetching resource list"
  • Swagger-ui local setup issue
  • Swagger ui in Rails
  • API description not show in Swagger UI
  • Swagger UI with multiple services
  • Swagger UI in ASP.NET Web API not adding url parameters
  • Swagger UI / Editor like page - add to my web site
  • Not able to get Swagger UI with spring boot
  • Change model schema for java.sql.Time in swagger-ui
  • WSO2 API Manager - Swagger UI fails to load (API Console)
  • Swagger UI parameter as list instead of text input
  • Is it possibe to add a login page before Swagger ui?
  • Response header is not getting rendered in swagger UI in Google Chrome, Mozilla Firefox
  • Anyone who used Swagger API framework ? I want to handle a model class generically in swagger UI
  • Swagger ui url with parameters
  • Swagger UI Download PDF
  • How to prepend a parameter in Swagger UI
  • I am using sails-swagger to generate the swagger docs i am getting only json format documnetation not swagger ui
  • Swagger UI setup in Web Api for endpoint and class documentation
  • Swagger UI 2.0 Customisazation
  • How do I request a client certificate when a call is made to Swagger UI / Swashbuckle?
  • Response header is not getting displayed in swagger UI rendered in Google chrome
  • REST API - ALPS UI (Swagger UI like)
  • How to integrate swagger-ui in my application
  • Spring REST API Swagger UI @ModelAttribute request URL and parameter type
  • How to get a json response from API to swagger UI
  • How can I get Swagger UI to show at the root url for my service
swagger-ui list of languages used
swagger-ui latest release notes
v3.12.1 Swagger-UI 3.12.1 Released!

Interface changes: none.

Changelog:

  • improvement: validator image hides until it is loaded (via #4287)
  • improvement: html sanitizer allows image src to be data: scheme (via #4236)
  • improvement: model properties and metadata more reliably sit on their own lines (via #4236)
v3.12.0 Swagger-UI 3.12.0 Released!

Interface changes: none.

Changelog:

  • feature: read Swagger 2.0 non-body parameter x-example fields and use them as initial values (via #3538)
  • improvement: urls and deepLinking options now play well together, by using location.replaceState to update the urls.primaryName setting in the browser query string (via #4181)
  • improvement: filter is now housed within a plugin, which allows custom filtering logic through the plugin system (via #4255)
  • improvement: generate more sensible example values when using anyOf and oneOf (via #4136)
  • improvement: add Close button to OAuth dialog, rename Done to Close elsewhere (via #4212)
  • improvement: add button to reset request body value when the user modifies it (via #4185)
  • fix: blob file download in internet explorer (via #4256)
  • fix: try-it-out consumes value regression (#4265)
  • fix: callback display regression, by using complete spec path to request resolved subtrees (via #4272)
  • fix: remote $ref resolution regression, by passing baseDoc to Swagger-Client (via #4273)
  • fix: deeplinked operation resolution on page load (via #4281)
  • dependency: upgraded to zenscroll@4.0.1 to solve a fatal error experienced by a small subset of users (via #4270)
v3.11.0 Swagger-UI 3.11.0 Released!

This release includes significant improvements to Swagger-UI's performance. The concept of an entirely-resolved spec representation has been done away with in favor of resolved subtrees: as the user expands operations and models in Swagger-UI, work is done to resolve only the parts needed for display. This allows us to do initial renders more quickly and paves the way for a more responsive editing experience in Swagger-Editor.

As a result, there are some breaking changes to various private APIs (mostly spec facilities that focus on the resolved state). If you run custom plugins that rely on that data, you'll want to check for compatibility before upgrading.

As a reminder: breaking private API changes result in a minor version bump, not a major bump.

Interface changes:

  • defaultModelsExpandDepth behavior has changed; the default 1 value now leaves all models collapsed for performance reasons related to the new lazy resolution.
  • specResolved is no longer updated by default; plugins that rely on it should move to specJson or specJsonWithResolvedSubtrees.

Changelog:

  • feature: lazy resolver (via #4249)
  • improvement: show OAuth error message when auth fails (via #4058)
  • fix: allow more valid GUIDs (via #4252)
  • fix: bump lodash dependency due to potential vulnerability (via #4224)
Other projects in JavaScript