diff --git a/.github/issue_template.md b/.github/issue_template.md index 1b519695..77c30a7e 100644 --- a/.github/issue_template.md +++ b/.github/issue_template.md @@ -1,3 +1,63 @@ -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 broswer & 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/.travis.yml b/.travis.yml index c9d09c8d..da8c805b 100644 --- a/.travis.yml +++ b/.travis.yml @@ -16,7 +16,7 @@ deploy: email: apiteam@swagger.io skip_cleanup: true api_key: - secure: "IJkLaACa+rfERf1O5nwlqOyuo9sbul3FBhBt4Un9P+DvEet3AoDPV9NQVLd8SkmQYKGbGQWF4BIdjrO5nqFD6Te+JTeUX5Uo/DFS/fu9qw1xv0dQpvbJFuoYnnFlbzGTEs4CFa8lbu3ZromFHQGOQxRobjsG1Kf0dWFSSzmND3g=" + secure: "YKk5L1BL4oAixvLjWp+i85fNFXK85HKOlUt6QypkZkt23My5aywuYsv5VCLjjOtuWc72zbmOzP82DTBsuRswCRViXWCiNYhl42QTdvadHu0uIlM/FL6aNlvPpzXIws4bMvz1aYOTzFTnSnNuvCTzF1daW0+2ClOo3r0nLEdDfFg=" on: tags: true repo: swagger-api/swagger-ui 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 dac53d35..57b1aaf8 100644 --- a/README.md +++ b/README.md @@ -18,16 +18,17 @@ This repo publishes to two different NPM packages: For the older version of swagger-ui, refer to the [*2.x branch*](https://github.com/swagger-api/swagger-ui/tree/2.x). ## Compatibility -The OpenAPI Specification has undergone 4 revisions since initial creation in 2010. Compatibility between swagger-ui and the OpenAPI Specification is as follows: +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 | Status ------------------- | ------------ | -------------------------- | ----- | ------ -3.0.19 | 2017-07-14 | 2.0 | [tag v3.0.19](https://github.com/swagger-api/swagger-ui/tree/v3.0.19) | -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) | -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) | -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) | -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) | +Swagger UI Version | Release Date | OpenAPI Spec compatibility | Notes +------------------ | ------------ | -------------------------- | ----- +3.1.4 | 2017-08-05 | 2.0, 3.0 | [tag v3.1.4](https://github.com/swagger-api/swagger-ui/tree/v3.1.4) +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) +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) +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) +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) ### How to run @@ -58,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. @@ -96,7 +106,8 @@ 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 --- | --- @@ -106,6 +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` ``` const ui = SwaggerUIBundle({...}) @@ -135,6 +147,7 @@ urls.primaryName | When using `urls`, you can use this subparameter. If the valu spec | A JSON object describing the OpenAPI Specification. When used, the `url` parameter will not be parsed. This is useful for testing manually-generated specifications without hosting them. validatorUrl | By default, Swagger-UI attempts to validate specs against swagger.io's online validator. You can use this parameter to set a different validator URL, for example for locally deployed validators ([Validator Badge](https://github.com/swagger-api/validator-badge)). Setting it to `null` will disable validation. dom_id | The id of a dom element inside which SwaggerUi will put the user interface for swagger. +domNode | The HTML DOM element inside which SwaggerUi will put the user interface for swagger. Overrides `dom_id`. oauth2RedirectUrl | OAuth redirect URL tagsSorter | Apply a sort to the tag list of each API. It can be 'alpha' (sort by paths alphanumerically) or a function (see [Array.prototype.sort()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) to learn how to write a sort function). Two tag name strings are passed to the sorter for each pass. Default is the order determined by Swagger-UI. operationsSorter | Apply a sort to the operation list of each API. It can be 'alpha' (sort by paths alphanumerically), 'method' (sort by HTTP method) or a function (see Array.prototype.sort() to know how sort function works). Default is the order returned by the server unchanged. 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/dist/index.html b/dist/index.html index f6aaf9e4..0de47c67 100644 --- a/dist/index.html +++ b/dist/index.html @@ -11,15 +11,15 @@