1 | # <img src="https://raw.githubusercontent.com/swagger-api/swagger.io/wordpress/images/assets/SWU-logo-clr.png" width="300">
|
2 |
|
3 | [![NPM version](https://badge.fury.io/js/swagger-ui.svg)](http://badge.fury.io/js/swagger-ui)
|
4 | [![Build Status](https://jenkins.swagger.io/view/OSS%20-%20JavaScript/job/oss-swagger-ui-master/badge/icon?subject=jenkins%20build)](https://jenkins.swagger.io/view/OSS%20-%20JavaScript/job/oss-swagger-ui-master/)
|
5 | [![npm audit](https://jenkins.swagger.io/buildStatus/icon?job=oss-swagger-ui-security-audit&subject=npm%20audit)](https://jenkins.swagger.io/job/oss-swagger-ui-security-audit/lastBuild/console)
|
6 | ![total GitHub contributors](https://img.shields.io/github/contributors-anon/swagger-api/swagger-ui.svg)
|
7 |
|
8 | ![monthly npm installs](https://img.shields.io/npm/dm/swagger-ui.svg?label=npm%20downloads)
|
9 | ![total docker pulls](https://img.shields.io/docker/pulls/swaggerapi/swagger-ui.svg)
|
10 | ![monthly packagist installs](https://img.shields.io/packagist/dm/swagger-api/swagger-ui.svg?label=packagist%20installs)
|
11 | ![gzip size](https://img.shields.io/bundlephobia/minzip/swagger-ui.svg?label=gzip%20size)
|
12 |
|
13 | **👉🏼 Want to score an easy open-source contribution?** Check out our [Good first issue](https://github.com/swagger-api/swagger-ui/issues?q=is%3Aissue+is%3Aopen+label%3A%22Good+first+issue%22) label.
|
14 |
|
15 | **🕰️ Looking for the older version of Swagger UI?** Refer to the [*2.x* branch](https://github.com/swagger-api/swagger-ui/tree/2.x).
|
16 |
|
17 |
|
18 | This repository publishes to three different NPM modules:
|
19 |
|
20 | * [swagger-ui](https://www.npmjs.com/package/swagger-ui) is a traditional npm module intended for use in single-page applications that are capable of resolving dependencies (via Webpack, Browserify, etc).
|
21 | * [swagger-ui-dist](https://www.npmjs.com/package/swagger-ui-dist) is a dependency-free module that includes everything you need to serve Swagger UI in a server-side project, or a single-page application that can't resolve npm module dependencies.
|
22 | * [swagger-ui-react](https://www.npmjs.com/package/swagger-ui-react) is Swagger UI packaged as a React component for use in React applications.
|
23 |
|
24 | We strongly suggest that you use `swagger-ui` instead of `swagger-ui-dist` if you're building a single-page application, since `swagger-ui-dist` is significantly larger.
|
25 |
|
26 |
|
27 | ## Compatibility
|
28 | The OpenAPI Specification has undergone 5 revisions since initial creation in 2010. Compatibility between Swagger UI and the OpenAPI Specification is as follows:
|
29 |
|
30 | Swagger UI Version | Release Date | OpenAPI Spec compatibility | Notes
|
31 | ------------------ | ------------ | -------------------------- | -----
|
32 | 3.18.3 | 2018-08-03 | 2.0, 3.0 | [tag v3.18.3](https://github.com/swagger-api/swagger-ui/tree/v3.18.3)
|
33 | 3.0.21 | 2017-07-26 | 2.0 | [tag v3.0.21](https://github.com/swagger-api/swagger-ui/tree/v3.0.21)
|
34 | 2.2.10 | 2017-01-04 | 1.1, 1.2, 2.0 | [tag v2.2.10](https://github.com/swagger-api/swagger-ui/tree/v2.2.10)
|
35 | 2.1.5 | 2016-07-20 | 1.1, 1.2, 2.0 | [tag v2.1.5](https://github.com/swagger-api/swagger-ui/tree/v2.1.5)
|
36 | 2.0.24 | 2014-09-12 | 1.1, 1.2 | [tag v2.0.24](https://github.com/swagger-api/swagger-ui/tree/v2.0.24)
|
37 | 1.0.13 | 2013-03-08 | 1.1, 1.2 | [tag v1.0.13](https://github.com/swagger-api/swagger-ui/tree/v1.0.13)
|
38 | 1.0.1 | 2011-10-11 | 1.0, 1.1 | [tag v1.0.1](https://github.com/swagger-api/swagger-ui/tree/v1.0.1)
|
39 |
|
40 | ## Documentation
|
41 |
|
42 | #### Usage
|
43 | - [Installation](docs/usage/installation.md)
|
44 | - [Configuration](docs/usage/configuration.md)
|
45 | - [CORS](docs/usage/cors.md)
|
46 | - [OAuth2](docs/usage/oauth2.md)
|
47 | - [Deep Linking](docs/usage/deep-linking.md)
|
48 | - [Limitations](docs/usage/limitations.md)
|
49 | - [Version detection](docs/usage/version-detection.md)
|
50 |
|
51 | #### Customization
|
52 | - [Overview](docs/customization/overview.md)
|
53 | - [Plugin API](docs/customization/plugin-api.md)
|
54 | - [Custom layout](docs/customization/custom-layout.md)
|
55 |
|
56 | #### Development
|
57 | - [Setting up](docs/development/setting-up.md)
|
58 | - [Scripts](docs/development/scripts.md)
|
59 |
|
60 | ##### Integration Tests
|
61 |
|
62 | You will need JDK of version 7 or higher as instructed here
|
63 | https://nightwatchjs.org/gettingstarted/#selenium-server-setup
|
64 |
|
65 | Integration tests can be run locally with `npm run e2e` - be sure you aren't running a dev server when testing!
|
66 |
|
67 | ### Browser support
|
68 | Swagger UI works in the latest versions of Chrome, Safari, Firefox, and Edge.
|
69 |
|
70 | ### Known Issues
|
71 |
|
72 | 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.
|
73 |
|
74 | - Only part of the parameters previously supported are available.
|
75 | - The JSON Form Editor is not implemented.
|
76 | - Support for `collectionFormat` is partial.
|
77 | - l10n (translations) is not implemented.
|
78 | - Relative path support for external files is not implemented.
|
79 |
|
80 | ## Security contact
|
81 |
|
82 | Please disclose any security-related issues or vulnerabilities by emailing [security@swagger.io](mailto:security@swagger.io), instead of using the public issue tracker.
|