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/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..57b1aaf8 100644 --- a/README.md +++ b/README.md @@ -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.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) @@ -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({...}) 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 52590951..0de47c67 100644 --- a/dist/index.html +++ b/dist/index.html @@ -11,15 +11,15 @@