{"id":13570143,"url":"https://github.com/ruby-grape/grape-swagger-rails","last_synced_at":"2025-05-14T03:11:52.963Z","repository":{"id":26687420,"uuid":"30144265","full_name":"ruby-grape/grape-swagger-rails","owner":"ruby-grape","description":"Swagger UI as Rails Engine for grape-swagger gem.","archived":false,"fork":false,"pushed_at":"2024-11-21T09:23:44.000Z","size":831,"stargazers_count":255,"open_issues_count":27,"forks_count":195,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-05-11T21:04:53.932Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ruby-grape.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-02-01T11:32:46.000Z","updated_at":"2025-04-29T10:05:20.000Z","dependencies_parsed_at":"2024-01-14T03:50:17.963Z","dependency_job_id":"f8c3c0b9-f0ea-46e3-9c0f-c31469581f91","html_url":"https://github.com/ruby-grape/grape-swagger-rails","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruby-grape%2Fgrape-swagger-rails","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruby-grape%2Fgrape-swagger-rails/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruby-grape%2Fgrape-swagger-rails/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruby-grape%2Fgrape-swagger-rails/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ruby-grape","download_url":"https://codeload.github.com/ruby-grape/grape-swagger-rails/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254059520,"owners_count":22007771,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T14:00:48.733Z","updated_at":"2025-05-14T03:11:47.949Z","avatar_url":"https://github.com/ruby-grape.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# GrapeSwaggerRails\n\n[![Gem Version](https://badge.fury.io/rb/grape-swagger-rails.svg)](http://badge.fury.io/rb/grape-swagger-rails)\n[![Tests](https://github.com/ruby-grape/grape-swagger-rails/actions/workflows/test.yml/badge.svg)](https://github.com/ruby-grape/grape-swagger-rails/actions/workflows/test.yml)\n[![Code Climate](https://codeclimate.com/github/ruby-grape/grape-swagger-rails/badges/gpa.svg)](https://codeclimate.com/github/ruby-grape/grape-swagger-rails)\n\nSwagger UI as Rails Engine for grape-swagger gem.\n\n# Table of Contents\n\n- [Installation](#installation)\n- [Compatibility](#compatibility)\n- [Usage](#usage)\n  - [Basic Authentication](#basic-authentication)\n  - [Pre-fill Authentication](#pre-fill-authentication)\n  - [API Token Authentication](#api-token-authentication)\n  - [Swagger UI Authorization](#swagger-ui-authorization)\n    - [Integration with DoorKeeper](#integration-with-doorkeeper)\n  - [Hiding the API or Authorization text boxes](#hiding-the-api-or-authorization-text-boxes)\n  - [Updating Swagger UI from Dist](#updating-swagger-ui-from-dist)\n  - [Enabling in a Rails-API Project](#enabling-in-a-rails-api-project)\n  - [Enabling in Rails 6 (Sprokets 5)](#enabling-in-rails-6-sprokets-5)\n- [Contributors](#contributors)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'grape-swagger-rails'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install grape-swagger-rails\n\n## Compatibility\n\nGrapeSwaggerRails is compatible with the following versions of grape and grape-swagger.\n\ngrape  | grape-swagger\n-------|--------------\n0.9.0  | 0.8.0\n0.10.0 | 0.9.0\n0.16.2 | 0.20.2\n1.8.0  | 1.6.1\n2.2.0  | 2.1.1\n\n## Usage\n\nAdd this line to `./config/routes.rb`:\n\n```ruby\nmount GrapeSwaggerRails::Engine =\u003e '/swagger'\n```\n\nCreate an initializer (e.g. `./config/initializers/swagger.rb`) and specify the URL to your Swagger API schema and app:\n\n```ruby\nGrapeSwaggerRails.options.url      = '/swagger_doc.json'\nGrapeSwaggerRails.options.app_url  = 'http://swagger.wordnik.com'\n```\n\nYou can dynamically set `app_url` for each request use a `before_action`:\n\n```ruby\nGrapeSwaggerRails.options.before_action do\n  GrapeSwaggerRails.options.app_url = request.protocol + request.host_with_port\nend\n```\n\nYou can set the app name, default is \"Swagger\".\n\n``` ruby\nGrapeSwaggerRails.options.app_name = 'Swagger'\n```\n\nYou can specify additional headers to add to each request:\n\n```ruby\nGrapeSwaggerRails.options.headers['Special-Header'] = 'Some Secret Value'\n```\n\nYou can set docExpansion with \"none\" or \"list\" or \"full\", default is \"none\".\nSee the official Swagger-UI documentation about [SwaggerUi Parameters](https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md#parameters).\n\n```ruby\nGrapeSwaggerRails.options.doc_expansion = 'list'\n```\n\nYou can set supportedSubmitMethods with an array of the supported HTTP methods, default is `%w{ get post put delete patch }`.\n\nSee the official Swagger-UI documentation about [SwaggerUi Parameters](https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md#parameters).\n\n```ruby\nGrapeSwaggerRails.options.supported_submit_methods = [\"get\"]\n```\n\nYou can set validatorUrl to your own locally deployed Swagger validator, or disable validation by setting this option to nil.\nThis is useful to avoid error messages when running Swagger-UI on a server which is not accessible from outside your network.\n\n```ruby\nGrapeSwaggerRails.options.validator_url = nil\n```\n\nUsing the `headers` option above, you could hard-code Basic Authentication credentials.\nAlternatively, you can configure Basic Authentication through the UI, as described below.\n\n### Basic Authentication\n\nIf your application uses Basic Authentication, you can setup Swagger to send the username and password to the server with each request to your API:\n\n```ruby\nGrapeSwaggerRails.options.api_auth     = 'basic' # Or 'bearer' for OAuth\nGrapeSwaggerRails.options.api_key_name = 'Authorization'\nGrapeSwaggerRails.options.api_key_type = 'header'\n```\n\nNow you can specify the username and password to your API in the Swagger \"API key\" field by concatenating the values like this:\n\n    username:password\n\nThe javascript that loads on the Swagger page automatically encodes the username and password and adds the authorization header to your API request.\nSee the official Swagger documentation about [Custom Header Parameters](https://github.com/wordnik/swagger-ui#custom-header-parameters---for-basic-auth-etc)\n\n### Pre-fill Authentication\n\nIf 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:\n\n```ruby\nGrapeSwaggerRails.options.api_key_default_value = 'your_default_value'\n```\n\nTo set it based on the `current_user` or other request-based parameters, try using it inside of your `before_action` (See Swagger UI Authorization)\n\n### API Token Authentication\n\nIf 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:\n\n```ruby\nGrapeSwaggerRails.options.api_key_name = 'api_token'\nGrapeSwaggerRails.options.api_key_type = 'query'\n```\n\nIf 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:\n\n```\nAuthorization: Token token=\"WCZZYjnOQFUYfJIN2ShH1iD24UHo58A6TI\"\n```\n\nby specify:\n\n```ruby\nGrapeSwaggerRails.options.api_auth = 'token'\nGrapeSwaggerRails.options.api_key_name = 'Authorization'\nGrapeSwaggerRails.options.api_key_type = 'header'\nGrapeSwaggerRails.options.api_key_placeholder = 'authorization_token'\n```\n\nYou can use the ```authorization_token``` input box to fill in your API token.\n### Swagger UI Authorization\n\nYou may want to authenticate users before displaying the Swagger UI, particularly when the API is protected by Basic Authentication.\nUse the `before` option to inspect the request before Swagger UI:\n\n```ruby\nGrapeSwaggerRails.options.before_action do |request|\n  # 1. Inspect the `request` or access the Swagger UI controller via `self`.\n  # 2. Check `current_user` or `can? :access, :api`, etc.\n  # 3. Redirect or error in case of failure.\nend\n```\n\n#### Integration with DoorKeeper\n\nAdd the following code to the initializer (swagger.rb):\n\n```ruby\nGrapeSwaggerRails.options.before_action do |request|\n  GrapeSwaggerRails.options.api_key_default_value = current_user.token.token\nend\n```\n\nIn your User model (user.rb) add:\n\n```ruby\nhas_one :token, -\u003e { order 'created_at DESC' }, class_name: Doorkeeper::AccessToken, foreign_key: :resource_owner_id\n```\n\n### Hiding the API or Authorization text boxes\n\nIf you know in advance that you would like to prevent changing the Swagger API URL, you can hide it using the following:\n\n```ruby\nGrapeSwaggerRails.options.hide_url_input = true\n```\n\nSimilarly, you can hide the Authentication input box by adding this:\n\n```ruby\nGrapeSwaggerRails.options.hide_api_key_input = true\n```\n\nBy default, these options are false.\n\n### Updating Swagger UI from Dist\n\nTo update Swagger UI from its [distribution](https://github.com/wordnik/swagger-ui), run `bundle exec rake swagger_ui:dist:update`. Examine the changes carefully.\n\nNOTE: This action should be run part of this gem (not your application). In case if you want to\nmake it up-to-date, clone the repo, run the rake task, examine the diff, fix any bugs, make sure\ntests pass and then send PR here.\n\n### Enabling in a Rails-API Project\n\nThe 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).\n\nAdd sprockets to `config/application.rb`.\n\n```ruby\nrequire 'sprockets/railtie'\n```\n\nInclude JavaScript in `app/assets/javascripts/application.js`.\n\n```javascript\n//\n//= require_tree .\n```\n\nInclude CSS stylesheets in `app/assets/stylesheets/application.css`.\n\n```css\n/*\n*= require_tree .\n*/\n```\n\n### Enabling in Rails 6 (Sprokets 5)\n\nRails 6 top-level targets are determined via `./app/assets/config/manifest.js`. Specify `grape-swagger-rails` asset files as follows.\n\n```javascript\n//= link grape_swagger_rails/application.css\n//= link grape_swagger_rails/application.js\n```\n\nSee [Upgrading Sprokets](https://github.com/rails/sprockets/blob/master/UPGRADING.md#manifestjs) for more information.\n\n## Contributors\n\n* [unloved](https://github.com/unloved)\n* [dapi](https://github.com/dapi)\n* [joelvh](https://github.com/joelvh)\n* [dblock](https://github.com/dblock)\n* ... and [more](https://github.com/ruby-grape/grape-swagger-rails/graphs/contributors) ...\n\n## Contributing\n\nSee [CONTRIBUTING](CONTRIBUTING.md).\n\n## License\n\nMIT License, see [LICENSE](LICENSE.txt).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruby-grape%2Fgrape-swagger-rails","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fruby-grape%2Fgrape-swagger-rails","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruby-grape%2Fgrape-swagger-rails/lists"}