Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mairu/swagger-ui-apikey-auth-form
Swagger UI Plugin to allow login with credentials for apiKey authentications and keep apiKey in localStorage
https://github.com/mairu/swagger-ui-apikey-auth-form
Last synced: 27 days ago
JSON representation
Swagger UI Plugin to allow login with credentials for apiKey authentications and keep apiKey in localStorage
- Host: GitHub
- URL: https://github.com/mairu/swagger-ui-apikey-auth-form
- Owner: Mairu
- License: mit
- Created: 2019-06-07T07:12:50.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2022-12-10T18:31:55.000Z (almost 2 years ago)
- Last Synced: 2024-10-15T04:33:18.020Z (about 1 month ago)
- Language: JavaScript
- Size: 1.12 MB
- Stars: 5
- Watchers: 2
- Forks: 1
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# Swagger UI Plugin ApiKeyAuthForm
[](https://www.npmjs.com/package/@mairu/swagger-ui-apikey-auth-form)
A plugin for Swagger UI to authenticate using credentials to generate a token which is used as apiKey header. Works also for bearer authentication of OpenApi V3.
Also keeps an api token in the localStorage if configured, which helps with page reloads (on development).
## Demo
A Demo of Swagger UI using this plugin as available [here](https://mairu.github.io/swagger-ui-apikey-auth-form/demo).
The credentials for the api key authentication are `user` with password `secret`.
## Compatibility
The plugin was developed using Swagger UI Version 3.22. As it uses internal APIs of Swagger UI,
they could change and break the plugin.
## Usage.
1. Make swagger-ui-apikey-auth-form.js available for use in your Swagger UI. There are different possibilities:
* Load it using https://unpkg.com/@mairu/[email protected]/dist/swagger-ui-apikey-auth-form.js (directly or copy to your project)
* Include '@mairu/swagger-ui-apikey-auth-form' to your dependencies and serve it from node_modules.
2. Include this script in your Swagger index.html (adjust the path to the method you use)
```
```
3. Then add the plugin to your Swagger UI config and also add needed configuration
```
const ui = SwaggerUIBundle({
// ...
plugins: [
// ...
SwaggerUIApiKeyAuthFormPlugin,
],
// ...
configs: {
apiKeyAuthFormPlugin: {
forms: {
apiKeyName: {
fields: {
fieldName: {
type: 'text',
label: 'Fieldname',
},
// ...
},
authCallback(values, callback) {
// do login stuff
// on error
callback('error message');
// on success
callback(null, 'the api key here');
// example using SwaggerUIs fetch api
ui.fn.fetch({
url: '/authenticate',
method: 'post',
headers: {
Accept: 'application/json',
'Content-Type': 'application/json',
},
body: JSON.stringify(value),
}).then(function (response) {
const json = JSON.parse(response.data);
if (json.token) {
callback(null, 'Bearer ' + json.token);
} else {
callback('error while login');
}
}).catch(function (err) {
console.log(err, Object.entries(err));
callback('error while login');
});
},
}
},
localStorage: {
apiKeyName: {}
}
}
}
});
```
## Configuration
The Plugin has to be configured to know for which apiKey a form should be added to the SwaggerUI and how to handle authentication.
For that you have to add the plugin config object in the `configs` of the SwaggerUI initialization with key name `apiKeyAuthFormPlugin`.
Here are the config options of the plugin config:
* **forms**
To add credentials fields to an api key authentication you have to add this object
with the name of the security definition of the api key as object key and an object with the following options as sub keys.
* **authCallback** (required)
Callback to perform the api key fetching or creation. The callback will get 2 parameters:
* **values** - object with form values
* **callback(error, apiKey)** - callback to provide api key or error (string)
* **containerStyle**
Object with css in react way for the container that holds the fields and the submit button.
If not provided the default is used `{ marginLeft: 20 }`
The container also has the class `auth-container-api-key-form` if other styles should be addressed.
* **fields**
Object of fields to render. If not provided the default is used
```
fields: {
username: {
type: 'text',
label: 'Username',
initialValue: 'hans',
},
password: {
type: 'password',
label: 'Password',
},
},
```
every field can have the keys: type, label, initialValue, rowProps, colProps, labelProps and inputProps
* **submitBtnLabel**
Simple string with Label for the submit button. Default is: 'Get Key with Credentials'
* **localStorage** -
If you want to keep api keys in the local storage you can configure that here.
It is an object with the name of the security definition of the api key as object key and the following options as sub keys.
* **key** -
Key which is used in localStorage, default would be
`` `SwUI_apiKeyAuth_${name}_${window.location.host}${window.location.pathname}` ``
* **ttl** -
Time how long an apiKey should be valid when read from localStorage in seconds, default is 3600 (1 hour)