diff --git a/.github/issue_template.md b/.github/issue_template.md index 1b519695..0c45b92b 100644 --- a/.github/issue_template.md +++ b/.github/issue_template.md @@ -1,3 +1,67 @@ -When reporting an issue, please provide the following details: -- swagger-ui version -- a swagger file reproducing the issue + + + + + + + +| Q | A +| ------------------------------- | ------- +| Bug or feature request? | +| Which Swagger/OpenAPI version? | +| Which Swagger-UI version? | +| How did you install Swagger-UI? | +| Which browser & version? | +| Which operating system? | + + +### Demonstration API definition + + + + + +```yaml +your: "API definition goes here" +``` + +### Configuration (browser query string, constructor, config.yaml) + + +```js +{ + "your": { "constructorConfig": "here" } +} +``` + +`?yourQueryStringConfig=here` + +### Expected Behavior + + + +### Current Behavior + + + +### Possible Solution + + + +### Context + + diff --git a/.gitignore b/.gitignore index 2e9dcf9c..8c713860 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,5 @@ npm-debug.log* .eslintcache package-lock.json *.iml +selenium-debug.log +test/e2e/db.json diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..3acb80b0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,54 @@ +## Contributing to Swagger-UI + +We love contributions from our community of users! This document explains our guidelines and workflows. Please take care to follow them, as it helps us keep things moving smoothly. + +#### Environment setup + +0. Install Node.js (4 or newer) and npm (3 or newer). +1. Make a fork of Swagger-UI on GitHub, then clone your fork to your machine. +2. Run `npm install` in your Swagger-UI directory. +3. Run `npm run dev`. `localhost:3200` should open automatically. +4. You're ready to go! + +#### Branching model + +Feature branches should be prefixed with `ft/`. + +Bugfix branches should be prefixed with `bug/`. + +Version branches should be prefixed with `v/`. + +After the forward slash, include a short description of what you're fixing. For example: `bug/fix-everything-that-was-broken`. For versions, add the version that will be released via the branch, for example: `v/1.2.3`. + +If there's an issue filed that you're addressing in your branch, include the issue number directly after the forward slash. For example: `bug/1234-fix-all-the-other-things`. + +#### Filing issues + +- **Do** include the Swagger-UI build you're using - you can find this by opening your console and checking `window.versions.swaggerUi` +- **Do** include a spec that demonstrates the issue you're experiencing. +- **Do** include screenshots, if needed. GIFs are even better! +- **Do** place code inside of a pre-formatted container by surrounding the code with triple backticks. +- **Don't** open tickets discussing issues with the Swagger/OpenAPI specification itself, or for issues with projects that use Swagger-UI. +- **Don't** open an issue without searching the issue tracker for duplicates first. + +#### Committing + +- Break your commits into logical atomic units. Well-segmented commits make it _much_ easier for others to step through your changes. +- Limit your subject (first) line to 50 characters (GitHub truncates more than 70). +- Provide a body if you'd like to explain your commit in detail. +- Capitalize the beginning of your subject line, and do not end the subject line with a period. +- Your subject line should complete this sentence: `If applied, this commit will [your subject line].` +- Don't use [magic GitHub words](https://help.github.com/articles/closing-issues-using-keywords/) in your commits to close issues - do that in the pull request for your code instead. + +_Adapted from [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/#seven-rules)._ + +#### Making pull requests + +- **Do** summarize your changes in the PR body. If in doubt, write a bullet-point list titled `This PR does the following:`. +- **Do** include references to issues that your PR solves, and use [magic GitHub words](https://help.github.com/articles/closing-issues-using-keywords/) to close those issues automatically when your PR is merged. +- **Do** include tests that cover new or changed functionality. +- **Do** be careful to follow our ESLint style rules. We recommend installing an ESLint plugin if you use a graphical code editor. +- **Do** make sure that tests and the linter are passing by running `npm test` locally, otherwise we can't merge your pull request. +- **Don't** include any changes to files in the `dist/` directory - we update those files only during releases. +- **Don't** mention maintainers in your original PR body - we probably would've seen it anyway, so it just increases the noise in our inboxes. Do feel free to ping maintainers if a week has passed and you've heard nothing from us. +- **Don't** open PRs for custom functionality that only serves a small subset of our users - custom functionality should be implemented outside of our codebase, via a plugin. diff --git a/README.md b/README.md index 172642c8..5c167806 100644 --- a/README.md +++ b/README.md @@ -10,10 +10,10 @@ As a brand new version, written from the ground up, there are some known issues and unimplemented features. Check out the [Known Issues](#known-issues) section for more details. -This repo publishes to two different NPM packages: +This repository publishes to two different NPM modules: -* [swagger-ui](https://www.npmjs.com/package/swagger-ui) is intended for use as a node module. -* [swagger-ui-dist](https://www.npmjs.com/package/swagger-ui-dist) comes pre-bundled with all dependencies and can be incorporated directly in a webapp. +* [swagger-ui](https://www.npmjs.com/package/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](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 web project that can't resolve npm module dependencies. For the older version of swagger-ui, refer to the [*2.x branch*](https://github.com/swagger-api/swagger-ui/tree/2.x). @@ -22,7 +22,7 @@ The OpenAPI Specification has undergone 5 revisions since initial creation in 20 Swagger UI Version | Release Date | OpenAPI Spec compatibility | Notes ------------------ | ------------ | -------------------------- | ----- -3.1.2 | 2017-07-31 | 2.0, 3.0 | [tag v3.1.2](https://github.com/swagger-api/swagger-ui/tree/v3.1.2) +3.2.1 | 2017-09-15 | 2.0, 3.0 | [tag v3.2.1](https://github.com/swagger-api/swagger-ui/tree/v3.2.1) 3.0.21 | 2017-07-26 | 2.0 | [tag v3.0.21](https://github.com/swagger-api/swagger-ui/tree/v3.0.21) 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) 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) @@ -46,7 +46,7 @@ Will start nginx with swagger-ui on port 80. Or you can provide your own swagger.json on your host ``` -docker run -p 80:8080 -e "SWAGGER_JSON=/foo/swagger.json" -v /bar:/foo swaggerapi/swagger-ui +docker run -p 80:8080 -e SWAGGER_JSON=/foo/swagger.json -v /bar:/foo swaggerapi/swagger-ui ``` ##### Prerequisites @@ -59,6 +59,15 @@ If you'd like to make modifications to the codebase, run the dev server with: `n If you'd like to rebuild the `/dist` folder with your codebase changes, run `npm run build`. + +##### 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. @@ -97,7 +106,7 @@ To use swagger-ui's bundles, you should take a look at the [source of swagger-ui #### OAuth2 configuration You can configure OAuth2 authorization by calling `initOAuth` method with passed configs under the instance of `SwaggerUIBundle` -default `client_id` and `client_secret`, `realm`, an application name `appName`, `scopeSeparator`, `additionalQueryStringParams`, +default `client_id` and `client_secret`, `realm`, an application name `appName`, `scopeSeparator`, `additionalQueryStringParams`, `useBasicAuthenticationWithAccessCodeGrant`. Config Name | Description @@ -108,7 +117,7 @@ realm | realm query parameter (for oauth1) added to `authorizationUrl` and `toke appName | application name, displayed in authorization popup. MUST be a string scopeSeparator | scope separator for passing scopes, encoded before calling, default value is a space (encoded value `%20`). MUST be a string additionalQueryStringParams | Additional query parameters added to `authorizationUrl` and `tokenUrl`. MUST be an object -useBasicAuthenticationWithAccessCodeGrant | Only activated for the `accessCode` flow. During the `authorization_code` request to the `tokenUrl`, pass the [Client Password](https://tools.ietf.org/html/rfc6749#section-2.3.1) using the HTTP Basic Authentication scheme (`Authorization` header with `Basic base64encoded[client_id:client_secret]`). The default is `false` +useBasicAuthenticationWithAccessCodeGrant | Only activated for the `accessCode` flow. During the `authorization_code` request to the `tokenUrl`, pass the [Client Password](https://tools.ietf.org/html/rfc6749#section-2.3.1) using the HTTP Basic Authentication scheme (`Authorization` header with `Basic base64encoded[client_id:client_secret]`). The default is `false` ``` const ui = SwaggerUIBundle({...}) @@ -151,6 +160,9 @@ displayRequestDuration | Controls the display of the request duration (in millis maxDisplayedTags | If set, limits the number of tagged operations displayed to at most this many. The default is to show all operations. filter | If set, enables filtering. The top bar will show an edit box that you can use to filter the tagged operations that are shown. Can be true/false to enable or disable, or an explicit filter string in which case filtering will be enabled using that string as the filter expression. Filtering is case sensitive matching the filter expression anywhere inside the tag. deepLinking | If set to `true`, enables dynamic deep linking for tags and operations. [Docs](https://github.com/swagger-api/swagger-ui/blob/master/docs/deep-linking.md) +requestInterceptor | MUST be a function. Function to intercept try-it-out requests. Accepts one argument requestInterceptor(request) and must return the potentially modified request. +responseInterceptor | MUST be a function. Function to intercept try-it-out responses. Accepts one argument responseInterceptor(response) and must return the potentially modified response. +showMutatedRequest | If set to `true` (the default), uses the mutated request returned from a rquestInterceptor to produce the curl command in the UI, otherwise the request before the requestInterceptor was applied is used. ### Plugins diff --git a/dev-helpers/index.html b/dev-helpers/index.html index a528687b..36c8cce9 100644 --- a/dev-helpers/index.html +++ b/dev-helpers/index.html @@ -21,7 +21,6 @@ { box-sizing: inherit; } - body { margin:0; background: #fafafa; diff --git a/dev-helpers/oauth2-redirect.html b/dev-helpers/oauth2-redirect.html index 00c7f014..a7eb162d 100644 --- a/dev-helpers/oauth2-redirect.html +++ b/dev-helpers/oauth2-redirect.html @@ -11,7 +11,11 @@ var redirectUrl = oauth2.redirectUrl; var isValid, qp, arr; - qp = (window.location.hash || location.search).substring(1); + if (/code|token|error/.test(window.location.hash)) { + qp = window.location.hash.substring(1); + } else { + qp = location.search.substring(1); + } arr = qp.split("&") arr.forEach(function (v,i,_arr) { _arr[i] = '"' + v.replace('=', '":"') + '"';}) diff --git a/dist/index.html b/dist/index.html index 52590951..0de47c67 100644 --- a/dist/index.html +++ b/dist/index.html @@ -11,15 +11,15 @@