You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
4
+
5
+
#### Environment setup
6
+
7
+
0. Install Node.js (4 or newer) and npm (3 or newer).
8
+
1. Make a fork of Swagger-UI on GitHub, then clone your fork to your machine.
9
+
2. Run `npm install` in your Swagger-UI directory.
10
+
3. Run `npm run dev`. `localhost:3200` should open automatically.
11
+
4. You're ready to go!
12
+
13
+
#### Branching model
14
+
15
+
Feature branches should be prefixed with `ft/`.
16
+
17
+
Bugfix branches should be prefixed with `bug/`.
18
+
19
+
Version branches should be prefixed with `v/`.
20
+
21
+
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`.
22
+
23
+
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`.
24
+
25
+
#### Filing issues
26
+
27
+
-**Do** include the Swagger-UI build you're using - you can find this by opening your console and checking `window.versions.swaggerUi`
28
+
-**Do** include a spec that demonstrates the issue you're experiencing.
29
+
-**Do** include screenshots, if needed. GIFs are even better!
30
+
-**Do** place code inside of a pre-formatted container by surrounding the code with triple backticks.
31
+
-**Don't** open tickets discussing issues with the Swagger/OpenAPI specification itself, or for issues with projects that use Swagger-UI.
32
+
-**Don't** open an issue without searching the issue tracker for duplicates first.
33
+
34
+
#### Committing
35
+
36
+
- Break your commits into logical atomic units. Well-segmented commits make it _much_ easier for others to step through your changes.
37
+
- Limit your subject (first) line to 50 characters (GitHub truncates more than 70).
38
+
- Provide a body if you'd like to explain your commit in detail.
39
+
- Capitalize the beginning of your subject line, and do not end the subject line with a period.
40
+
- Your subject line should complete this sentence: `If applied, this commit will [your subject line].`
41
+
- 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.
42
+
43
+
_Adapted from [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/#seven-rules)._
44
+
45
+
#### Making pull requests
46
+
47
+
-**Do** summarize your changes in the PR body. If in doubt, write a bullet-point list titled `This PR does the following:`.
48
+
-**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.
49
+
-**Do** include tests that cover new or changed functionality.
50
+
-**Do** be careful to follow our ESLint style rules. We recommend installing an ESLint plugin if you use a graphical code editor.
51
+
-**Do** make sure that tests and the linter are passing by running `npm test` locally, otherwise we can't merge your pull request.
52
+
-**Don't** include any changes to files in the `dist/` directory - we update those files only during releases.
53
+
-**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.
54
+
-**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.
Copy file name to clipboardExpand all lines: README.md
+23-10Lines changed: 23 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,16 +18,17 @@ This repo publishes to two different NPM packages:
18
18
For the older version of swagger-ui, refer to the [*2.x branch*](https://github.com/swagger-api/swagger-ui/tree/2.x).
19
19
20
20
## Compatibility
21
-
The OpenAPI Specification has undergone 4 revisions since initial creation in 2010. Compatibility between swagger-ui and the OpenAPI Specification is as follows:
21
+
The OpenAPI Specification has undergone 5 revisions since initial creation in 2010. Compatibility between swagger-ui and the OpenAPI Specification is as follows:
22
22
23
-
Swagger UI Version | Release Date | OpenAPI Spec compatibility | Notes | Status
Integration tests can be run locally with `npm run e2e` - be sure you aren't running a dev server when testing!
69
+
70
+
61
71
##### Browser support
62
72
Swagger UI works in the latest versions of Chrome, Safari, Firefox, Edge and IE11.
63
73
@@ -96,7 +106,8 @@ To use swagger-ui's bundles, you should take a look at the [source of swagger-ui
96
106
97
107
#### OAuth2 configuration
98
108
You can configure OAuth2 authorization by calling `initOAuth` method with passed configs under the instance of `SwaggerUIBundle`
99
-
default `client_id` and `client_secret`, `realm`, an application name `appName`, `scopeSeparator`, `additionalQueryStringParams`.
109
+
default `client_id` and `client_secret`, `realm`, an application name `appName`, `scopeSeparator`, `additionalQueryStringParams`,
110
+
`useBasicAuthenticationWithAccessCodeGrant`.
100
111
101
112
Config Name | Description
102
113
--- | ---
@@ -106,6 +117,7 @@ realm | realm query parameter (for oauth1) added to `authorizationUrl` and `toke
106
117
appName | application name, displayed in authorization popup. MUST be a string
107
118
scopeSeparator | scope separator for passing scopes, encoded before calling, default value is a space (encoded value `%20`). MUST be a string
108
119
additionalQueryStringParams | Additional query parameters added to `authorizationUrl` and `tokenUrl`. MUST be an object
120
+
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`
109
121
110
122
```
111
123
const ui = SwaggerUIBundle({...})
@@ -135,6 +147,7 @@ urls.primaryName | When using `urls`, you can use this subparameter. If the valu
135
147
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.
136
148
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.
137
149
dom_id | The id of a dom element inside which SwaggerUi will put the user interface for swagger.
150
+
domNode | The HTML DOM element inside which SwaggerUi will put the user interface for swagger. Overrides `dom_id`.
138
151
oauth2RedirectUrl | OAuth redirect URL
139
152
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.
140
153
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.
0 commit comments