<commit_before># grape-swagger

[![Build Status](https://travis-ci.org/tim-vandecasteele/grape-swagger.svg?branch=master)](https://travis-ci.org/tim-vandecasteele/grape-swagger)

## What is grape-swagger?

The grape-swagger gem provides an autogenerated documentation for your [Grape](https://github.com/intridea/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.wordnik.com) to your API.

![Demo Screenshot](test/splines.png)

## Related Projects

* [Grape](https://github.com/intridea/grape)
* [Swagger UI](https://github.com/wordnik/swagger-ui)

## Installation

Add to your Gemfile:

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

## 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.json'. See [test/api.rb](test/api.rb) for a simple demo.


``` ruby
require 'grape-swagger'

module API
  class Root < Grape::API
    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.json).

### CORS

If you use the online demo, make sure your API supports foreign requests by enabling CORS in Grape, otherwise you'll see the API description, but requests on the API won't return. Use [rack-cors](https://github.com/cyu/rack-cors) to enable CORS.

```` ruby
require 'rack/cors'
use Rack::Cors do
  allow do
    origins '*'
    resource '*', headers: :any, methods: [ :get, :post, :put, :delete, :options ]
  end
end
```

Alternatively you can set CORS headers in a Grape `before` block.

``` ruby
before do
  header['Access-Control-Allow-Origin'] = '*'
  header['Access-Control-Request-Method'] = '*'
end
````

## Configure

You can pass a hash with optional configuration settings to ```add_swagger_documentation```.

#### target_class

The API class to document, default `self`.

#### mount_path

The path where the API documentation is loaded, default is `/swagger_doc`.

#### class_name

API class name.

#### markdown

Allow markdown in `notes`, default is `false`. See below for details.

#### hide_format

Don't add `.(format)` to the end of URLs, default is `false`.

#### api_version

Version of the API that's being exposed.

#### base_path

Base path of the API that's being exposed. This configuration parameter accepts a `proc` to evaluate `base_path`, useful when you need to use request attributes to determine its value.

#### authorizations

This value is added to the `authorizations` key in the JSON documentation.

#### include_base_url

Add base path to the URLs, default is `true`.

#### root_base_path

Add `basePath` key to the JSON documentation, default is `true`.

#### models

A list of entities to document. Combine with the [grape-entity](https://github.com/intridea/grape-entity) gem. See below for details.<commit_msg>remove include_base_url option from documentation<commit_after># grape-swagger

[![Build Status](https://travis-ci.org/tim-vandecasteele/grape-swagger.svg?branch=master)](https://travis-ci.org/tim-vandecasteele/grape-swagger)

## What is grape-swagger?

The grape-swagger gem provides an autogenerated documentation for your [Grape](https://github.com/intridea/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.wordnik.com) to your API.

![Demo Screenshot](test/splines.png)

## Related Projects

* [Grape](https://github.com/intridea/grape)
* [Swagger UI](https://github.com/wordnik/swagger-ui)

## Installation

Add to your Gemfile:

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

## 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.json'. See [test/api.rb](test/api.rb) for a simple demo.


``` ruby
require 'grape-swagger'

module API
  class Root < Grape::API
    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.json).

### CORS

If you use the online demo, make sure your API supports foreign requests by enabling CORS in Grape, otherwise you'll see the API description, but requests on the API won't return. Use [rack-cors](https://github.com/cyu/rack-cors) to enable CORS.

```` ruby
require 'rack/cors'
use Rack::Cors do
  allow do
    origins '*'
    resource '*', headers: :any, methods: [ :get, :post, :put, :delete, :options ]
  end
end
```

Alternatively you can set CORS headers in a Grape `before` block.

``` ruby
before do
  header['Access-Control-Allow-Origin'] = '*'
  header['Access-Control-Request-Method'] = '*'
end
````

## Configure

You can pass a hash with optional configuration settings to ```add_swagger_documentation```.

#### target_class

The API class to document, default `self`.

#### mount_path

The path where the API documentation is loaded, default is `/swagger_doc`.

#### class_name

API class name.

#### markdown

Allow markdown in `notes`, default is `false`. See below for details.

#### hide_format

Don't add `.(format)` to the end of URLs, default is `false`.

#### api_version

Version of the API that's being exposed.

#### base_path

Base path of the API that's being exposed. This configuration parameter accepts a `proc` to evaluate `base_path`, useful when you need to use request attributes to determine its value.

#### authorizations

This value is added to the `authorizations` key in the JSON documentation.

#### root_base_path

Add `basePath` key to the JSON documentation, default is `true`.

#### models

A list of entities to document. Combine with the [grape-entity](https://github.com/intridea/grape-entity) gem. See below for details.
{'fraction_non_alphanumeric': 0.12211221122112212, 'fraction_numerical': 0.0012001200120012002, 'mean_word_length': 4.5236122618061305, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 3, 'https://': 18, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5464122', 'n_tokens_mistral': 2095, 'n_tokens_neox': 2009, 'n_words': 737}