Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ruby-grape/grape-swagger-rails
Swagger UI as Rails Engine for grape-swagger gem.
https://github.com/ruby-grape/grape-swagger-rails
Last synced: 3 days ago
JSON representation
Swagger UI as Rails Engine for grape-swagger gem.
- Host: GitHub
- URL: https://github.com/ruby-grape/grape-swagger-rails
- Owner: ruby-grape
- License: mit
- Created: 2015-02-01T11:32:46.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2024-09-24T02:12:24.000Z (about 2 months ago)
- Last Synced: 2024-11-05T02:36:14.208Z (9 days ago)
- Language: JavaScript
- Homepage:
- Size: 821 KB
- Stars: 251
- Watchers: 13
- Forks: 197
- Open Issues: 26
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# GrapeSwaggerRails
[](http://badge.fury.io/rb/grape-swagger-rails)
[](https://github.com/ruby-grape/grape-swagger-rails/actions/workflows/test.yml)
[](https://codeclimate.com/github/ruby-grape/grape-swagger-rails)
Swagger UI as Rails Engine for grape-swagger gem.
# Table of Contents
- [Installation](#installation)
- [Compatibility](#compatibility)
- [Usage](#usage)
- [Basic Authentication](#basic-authentication)
- [Pre-fill Authentication](#pre-fill-authentication)
- [API Token Authentication](#api-token-authentication)
- [Swagger UI Authorization](#swagger-ui-authorization)
- [Integration with DoorKeeper](#integration-with-doorkeeper)
- [Hiding the API or Authorization text boxes](#hiding-the-api-or-authorization-text-boxes)
- [Updating Swagger UI from Dist](#updating-swagger-ui-from-dist)
- [Enabling in a Rails-API Project](#enabling-in-a-rails-api-project)
- [Enabling in Rails 6 (Sprokets 5)](#enabling-in-rails-6-sprokets-5)
- [Contributors](#contributors)
- [Contributing](#contributing)
- [License](#license)
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'grape-swagger-rails'
```
And then execute:
$ bundle
Or install it yourself as:
$ gem install grape-swagger-rails
## Compatibility
GrapeSwaggerRails is compatible with the following versions of grape and grape-swagger.
grape | grape-swagger
-------|--------------
0.9.0 | 0.8.0
0.10.0 | 0.9.0
0.16.2 | 0.20.2
1.8.0 | 1.6.1
2.2.0 | 2.1.1
## Usage
Add this line to `./config/routes.rb`:
```ruby
mount GrapeSwaggerRails::Engine => '/swagger'
```
Create an initializer (e.g. `./config/initializers/swagger.rb`) and specify the URL to your Swagger API schema and app:
```ruby
GrapeSwaggerRails.options.url = '/swagger_doc.json'
GrapeSwaggerRails.options.app_url = 'http://swagger.wordnik.com'
```
You can dynamically set `app_url` for each request use a `before_action`:
```ruby
GrapeSwaggerRails.options.before_action do
GrapeSwaggerRails.options.app_url = request.protocol + request.host_with_port
end
```
You can set the app name, default is "Swagger".
``` ruby
GrapeSwaggerRails.options.app_name = 'Swagger'
```
You can specify additional headers to add to each request:
```ruby
GrapeSwaggerRails.options.headers['Special-Header'] = 'Some Secret Value'
```
You can set docExpansion with "none" or "list" or "full", default is "none".
See the official Swagger-UI documentation about [SwaggerUi Parameters](https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md#parameters).
```ruby
GrapeSwaggerRails.options.doc_expansion = 'list'
```
You can set supportedSubmitMethods with an array of the supported HTTP methods, default is `%w{ get post put delete patch }`.
See the official Swagger-UI documentation about [SwaggerUi Parameters](https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md#parameters).
```ruby
GrapeSwaggerRails.options.supported_submit_methods = ["get"]
```
You can set validatorUrl to your own locally deployed Swagger validator, or disable validation by setting this option to nil.
This is useful to avoid error messages when running Swagger-UI on a server which is not accessible from outside your network.
```ruby
GrapeSwaggerRails.options.validator_url = nil
```
Using the `headers` option above, you could hard-code Basic Authentication credentials.
Alternatively, you can configure Basic Authentication through the UI, as described below.
### Basic Authentication
If your application uses Basic Authentication, you can setup Swagger to send the username and password to the server with each request to your API:
```ruby
GrapeSwaggerRails.options.api_auth = 'basic' # Or 'bearer' for OAuth
GrapeSwaggerRails.options.api_key_name = 'Authorization'
GrapeSwaggerRails.options.api_key_type = 'header'
```
Now you can specify the username and password to your API in the Swagger "API key" field by concatenating the values like this:
username:password
The javascript that loads on the Swagger page automatically encodes the username and password and adds the authorization header to your API request.
See the official Swagger documentation about [Custom Header Parameters](https://github.com/wordnik/swagger-ui#custom-header-parameters---for-basic-auth-etc)
### Pre-fill Authentication
If you will know the Authentication key prior to page load or you wish to set it for debug purposes, you can setup so that the `api_key` field is pre-filled on page load:
```ruby
GrapeSwaggerRails.options.api_key_default_value = 'your_default_value'
```
To set it based on the `current_user` or other request-based parameters, try using it inside of your `before_action` (See Swagger UI Authorization)
### API Token Authentication
If your application uses token authentication passed as a query param, you can setup Swagger to send the API token along with each request to your API:
```ruby
GrapeSwaggerRails.options.api_key_name = 'api_token'
GrapeSwaggerRails.options.api_key_type = 'query'
```
If your application used token authentication passed as a header, like Rails does (`authenticate_or_request_with_http_token`), you can configure Swagger to send the token in this form:
```
Authorization: Token token="WCZZYjnOQFUYfJIN2ShH1iD24UHo58A6TI"
```
by specify:
```ruby
GrapeSwaggerRails.options.api_auth = 'token'
GrapeSwaggerRails.options.api_key_name = 'Authorization'
GrapeSwaggerRails.options.api_key_type = 'header'
GrapeSwaggerRails.options.api_key_placeholder = 'authorization_token'
```
You can use the ```authorization_token``` input box to fill in your API token.
### Swagger UI Authorization
You may want to authenticate users before displaying the Swagger UI, particularly when the API is protected by Basic Authentication.
Use the `before` option to inspect the request before Swagger UI:
```ruby
GrapeSwaggerRails.options.before_action do |request|
# 1. Inspect the `request` or access the Swagger UI controller via `self`.
# 2. Check `current_user` or `can? :access, :api`, etc.
# 3. Redirect or error in case of failure.
end
```
#### Integration with DoorKeeper
Add the following code to the initializer (swagger.rb):
```ruby
GrapeSwaggerRails.options.before_action do |request|
GrapeSwaggerRails.options.api_key_default_value = current_user.token.token
end
```
In your User model (user.rb) add:
```ruby
has_one :token, -> { order 'created_at DESC' }, class_name: Doorkeeper::AccessToken, foreign_key: :resource_owner_id
```
### Hiding the API or Authorization text boxes
If you know in advance that you would like to prevent changing the Swagger API URL, you can hide it using the following:
```ruby
GrapeSwaggerRails.options.hide_url_input = true
```
Similarly, you can hide the Authentication input box by adding this:
```ruby
GrapeSwaggerRails.options.hide_api_key_input = true
```
By default, these options are false.
### Updating Swagger UI from Dist
To update Swagger UI from its [distribution](https://github.com/wordnik/swagger-ui), run `bundle exec rake swagger_ui:dist:update`. Examine the changes carefully.
NOTE: This action should be run part of this gem (not your application). In case if you want to
make it up-to-date, clone the repo, run the rake task, examine the diff, fix any bugs, make sure
tests pass and then send PR here.
### Enabling in a Rails-API Project
The grape-swagger-rails gem uses the Rails asset pipeline for its Javascript and CSS. Enable the asset pipeline with [rails-api](https://github.com/rails-api/rails-api).
Add sprockets to `config/application.rb`.
```ruby
require 'sprockets/railtie'
```
Include JavaScript in `app/assets/javascripts/application.js`.
```javascript
//
//= require_tree .
```
Include CSS stylesheets in `app/assets/stylesheets/application.css`.
```css
/*
*= require_tree .
*/
```
### Enabling in Rails 6 (Sprokets 5)
Rails 6 top-level targets are determined via `./app/assets/config/manifest.js`. Specify `grape-swagger-rails` asset files as follows.
```javascript
//= link grape_swagger_rails/application.css
//= link grape_swagger_rails/application.js
```
See [Upgrading Sprokets](https://github.com/rails/sprockets/blob/master/UPGRADING.md#manifestjs) for more information.
## Contributors
* [unloved](https://github.com/unloved)
* [dapi](https://github.com/dapi)
* [joelvh](https://github.com/joelvh)
* [dblock](https://github.com/dblock)
* ... and [more](https://github.com/ruby-grape/grape-swagger-rails/graphs/contributors) ...
## Contributing
See [CONTRIBUTING](CONTRIBUTING.md).
## License
MIT License, see [LICENSE](LICENSE.txt).