<commit_before>[![Gem Version](https://badge.fury.io/rb/grape-swagger.svg)](http://badge.fury.io/rb/grape-swagger)
[![Build Status](https://travis-ci.org/ruby-grape/grape-swagger.svg?branch=master)](https://travis-ci.org/ruby-grape/grape-swagger)
[![Coverage Status](https://coveralls.io/repos/github/ruby-grape/grape-swagger/badge.svg?branch=master)](https://coveralls.io/github/ruby-grape/grape-swagger?branch=master)
[![Dependency Status](https://gemnasium.com/ruby-grape/grape-swagger.svg)](https://gemnasium.com/ruby-grape/grape-swagger)
[![Code Climate](https://codeclimate.com/github/ruby-grape/grape-swagger.svg)](https://codeclimate.com/github/ruby-grape/grape-swagger)

##### Table of Contents

* [What is grape-swagger?](#what)
* [Related Projects](#related)
* [Compatibility](#version)
* [Swagger-Spec](#swagger-spec)
* [Installation](#install)
* [Usage](#usage)
* [Model Parsers](#model_parsers)
* [Configure](#configure)
* [Routes Configuration](#routes)
* [Using Grape Entities](#grape-entity)
* [Securing the Swagger UI](#oauth)
* [Markdown (deprecated)](#md_usage)
* [Example](#example)
* [Rake Tasks](#rake)


## What is grape-swagger? <a name="what" />

The grape-swagger gem provides an autogenerated documentation for your [Grape](https://github.com/ruby-grape/grape) API. The generated documentation is Swagger-compliant, meaning it can easily be discovered in [Swagger UI](https://github.com/wordnik/swagger-ui). You should be able to point [the petstore demo](http://petstore.swagger.io/) to your API.

![Demo Screenshot](example/swagger-example.png)

This screenshot is based on the [Hussars](https://github.com/LeFnord/hussars) sample app.


## Related Projects <a name="related" />

* [Grape](https://github.com/ruby-grape/grape)
* [Grape Swagger Entity](https://github.com/ruby-grape/grape-swagger-entity)
  * [Grape Entity](https://github.com/ruby-grape/grape-entity)
* [Grape Swagger Representable](https://github.com/ruby-grape/grape-swagger-representable)
* [Swagger UI](https://github.com/wordnik/swagger-ui)



## Compatibility <a name="version" />

The following versions of grape, grape-entity and grape-swagger can currently be used together.

grape-swagger | swagger spec | grape                   | grape-entity | representable |
--------------|--------------|-------------------------|--------------|---------------|
0.10.5        |     1.2      | >= 0.10.0 ... <= 0.14.0 |  < 0.5.0     | n/a           |
0.11.0        |     1.2      |               >= 0.16.2 |  < 0.5.0     | n/a           |
0.25.2        |     2.0      | >= 0.14.0 ... <= 0.18.0 | <= 0.6.0     | >= 2.4.1      |
0.26.0        |     2.0      | >= 0.16.2               | <= 0.6.1     | >= 2.4.1      |
0.27.0        |     2.0      | >= 0.16.2               | => 0.5.0     | >= 2.4.1      |


## Swagger-Spec <a name="swagger-spec" />

Grape-swagger generates documentation per [Swagger / OpenAPI Spec 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md).

<!-- validating it with: http://bigstickcarpet.com/swagger-parser/www/index.html -->


## Installation <a name="install" />

Add to your Gemfile:

```ruby
gem 'grape-swagger'
```

## Upgrade

Please see [UPGRADING](UPGRADING.md) when upgrading from a previous version.



## Usage <a name="usage" />

Mount all your different APIs (with ```Grape::API``` superclass) on a root node. In the root class definition, include ```add_swagger_documentation```, this sets up the system and registers the documentation on '/swagger_doc'. See [example/config.ru](example/config.ru) for a simple demo.


```ruby
require 'grape-swagger'

module API
  class Root < Grape::API
    format :json
    mount API::Cats
    mount API::Dogs
    mount API::Pirates
    add_swagger_documentation
  end
end
```

To explore your API, either download [Swagger UI](https://github.com/wordnik/swagger-ui) and set it up yourself or go to the [online swagger demo](http://petstore.swagger.wordnik.com/) and enter your localhost url documentation root in the url field (probably something in the line of http://localhost:3000/swagger_doc).



## Model Parsers <a name="model_parsers" />

Since 0.21.0, `Grape::Entity` is not a part of grape-swagger, you need to add `grape-swagger-entity` manually to your Gemfile.
Also added support for [representable](https://github.com/apotonick/representable) via `grape-swagger-representable`.

```ruby
# For Grape::Entity ( https://github.com/ruby-grape/grape-entity )
gem 'grape-swagger-entity'
# For representable ( https://github.com/apotonick/representable )
gem 'grape-swagger-representable'
```

If you are not using Rails, make sure to load the parser inside your application initialization logic, e.g., via `require 'grape-swagger/entity'` or `require 'grape-swagger/representable`.

### Custom Model Parsers

You can create your own model parser, for example for [roar](https://github.com/apotonick/roar).
<commit_msg>Fix missing quotation mark in README (#638)<commit_after>[![Gem Version](https://badge.fury.io/rb/grape-swagger.svg)](http://badge.fury.io/rb/grape-swagger)
[![Build Status](https://travis-ci.org/ruby-grape/grape-swagger.svg?branch=master)](https://travis-ci.org/ruby-grape/grape-swagger)
[![Coverage Status](https://coveralls.io/repos/github/ruby-grape/grape-swagger/badge.svg?branch=master)](https://coveralls.io/github/ruby-grape/grape-swagger?branch=master)
[![Dependency Status](https://gemnasium.com/ruby-grape/grape-swagger.svg)](https://gemnasium.com/ruby-grape/grape-swagger)
[![Code Climate](https://codeclimate.com/github/ruby-grape/grape-swagger.svg)](https://codeclimate.com/github/ruby-grape/grape-swagger)

##### Table of Contents

* [What is grape-swagger?](#what)
* [Related Projects](#related)
* [Compatibility](#version)
* [Swagger-Spec](#swagger-spec)
* [Installation](#install)
* [Usage](#usage)
* [Model Parsers](#model_parsers)
* [Configure](#configure)
* [Routes Configuration](#routes)
* [Using Grape Entities](#grape-entity)
* [Securing the Swagger UI](#oauth)
* [Markdown (deprecated)](#md_usage)
* [Example](#example)
* [Rake Tasks](#rake)


## What is grape-swagger? <a name="what" />

The grape-swagger gem provides an autogenerated documentation for your [Grape](https://github.com/ruby-grape/grape) API. The generated documentation is Swagger-compliant, meaning it can easily be discovered in [Swagger UI](https://github.com/wordnik/swagger-ui). You should be able to point [the petstore demo](http://petstore.swagger.io/) to your API.

![Demo Screenshot](example/swagger-example.png)

This screenshot is based on the [Hussars](https://github.com/LeFnord/hussars) sample app.


## Related Projects <a name="related" />

* [Grape](https://github.com/ruby-grape/grape)
* [Grape Swagger Entity](https://github.com/ruby-grape/grape-swagger-entity)
  * [Grape Entity](https://github.com/ruby-grape/grape-entity)
* [Grape Swagger Representable](https://github.com/ruby-grape/grape-swagger-representable)
* [Swagger UI](https://github.com/wordnik/swagger-ui)



## Compatibility <a name="version" />

The following versions of grape, grape-entity and grape-swagger can currently be used together.

grape-swagger | swagger spec | grape                   | grape-entity | representable |
--------------|--------------|-------------------------|--------------|---------------|
0.10.5        |     1.2      | >= 0.10.0 ... <= 0.14.0 |  < 0.5.0     | n/a           |
0.11.0        |     1.2      |               >= 0.16.2 |  < 0.5.0     | n/a           |
0.25.2        |     2.0      | >= 0.14.0 ... <= 0.18.0 | <= 0.6.0     | >= 2.4.1      |
0.26.0        |     2.0      | >= 0.16.2               | <= 0.6.1     | >= 2.4.1      |
0.27.0        |     2.0      | >= 0.16.2               | => 0.5.0     | >= 2.4.1      |


## Swagger-Spec <a name="swagger-spec" />

Grape-swagger generates documentation per [Swagger / OpenAPI Spec 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md).

<!-- validating it with: http://bigstickcarpet.com/swagger-parser/www/index.html -->


## Installation <a name="install" />

Add to your Gemfile:

```ruby
gem 'grape-swagger'
```

## Upgrade

Please see [UPGRADING](UPGRADING.md) when upgrading from a previous version.



## Usage <a name="usage" />

Mount all your different APIs (with ```Grape::API``` superclass) on a root node. In the root class definition, include ```add_swagger_documentation```, this sets up the system and registers the documentation on '/swagger_doc'. See [example/config.ru](example/config.ru) for a simple demo.


```ruby
require 'grape-swagger'

module API
  class Root < Grape::API
    format :json
    mount API::Cats
    mount API::Dogs
    mount API::Pirates
    add_swagger_documentation
  end
end
```

To explore your API, either download [Swagger UI](https://github.com/wordnik/swagger-ui) and set it up yourself or go to the [online swagger demo](http://petstore.swagger.wordnik.com/) and enter your localhost url documentation root in the url field (probably something in the line of http://localhost:3000/swagger_doc).



## Model Parsers <a name="model_parsers" />

Since 0.21.0, `Grape::Entity` is not a part of grape-swagger, you need to add `grape-swagger-entity` manually to your Gemfile.
Also added support for [representable](https://github.com/apotonick/representable) via `grape-swagger-representable`.

```ruby
# For Grape::Entity ( https://github.com/ruby-grape/grape-entity )
gem 'grape-swagger-entity'
# For representable ( https://github.com/apotonick/representable )
gem 'grape-swagger-representable'
```

If you are not using Rails, make sure to load the parser inside your application initialization logic, e.g., via `require 'grape-swagger/entity'` or `require 'grape-swagger/representable'`.

### Custom Model Parsers

You can create your own model parser, for example for [roar](https://github.com/apotonick/roar).

{'fraction_non_alphanumeric': 0.17532138880453488, 'fraction_numerical': 0.019333940682255288, 'mean_word_length': 3.3658859920459565, 'pattern_counts': {'":': 0, '<': 33, '<?xml version=': 0, '>': 37, 'https://': 46, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6281212', 'n_tokens_mistral': 3541, 'n_tokens_neox': 3263, 'n_words': 736}