#Grape Demo

Demo project showing how to create an API with Rails, Grape, Swagger and Mongoid.

##Pre-Requisites

• Linux or OSX dev environment
• RVM and Ruby
• MongoDB
• Rails and Bundler

Vagrant configuration for a ready-to-go Ubuntu environment is provided with this demo. If you chose to use this, install Vagrant and simply run vagrant up from your project folder.

The rest of this guide assumes you are in the terminal of the vagrant machine, which is accessed via vagrant ssh in the project folder.

##Initial Setup

###Create Rails project

Go to your project folder and generate the new rails app

cd /vagrant
rails new demo
cd demo

###Install Grape Add gem “grape” to your Gemfile and bundle install

###Install Mongoid Add gem “mongoid” to your Gemfile and bundle install Generate the mongoid config rails g mongoid:config

##Build the API

###Create some models

rails g model article title:string content:text published_on:date
rails g model author name:string

Notice that the models are already set up as Mongoid Documents

class Article
  include Mongoid::Document
  field :title, type: String
  field :content, type: String
  field :published_on, type: Date
end

class Author
  include Mongoid::Document
  field :name, type: String
end

###Mount the API base

Add the following in config/routes.rb

mount API::Base => '/api'

###Create the API controllers Grape allows some freedom as to how you structure the API files. I prefer to place them under app/controllers/api but there are other options such as placing them under app/api mentioned in the Grape wiki.

cd /vagrant/demo
mkdir app/controllers/api
mkdir app/controllers/api/v1

We will create the following files:

• api/base.rb the main API base which handles routing of the API versions
• api/v1/base.rb the v1 base file
• api/v1/common.rb the shared configurations and functions for all v1 APIs
• api/v1/articles.rb
• api/v1/authors.rb

###Testing the initial APIs

Go to /vagrant/demo and run rails server, the vagrant machine is set to forward the default webrick port to port 3333 on the host so the app will respond on http://localhost:3333/

Included in the project is a folder with a Postman collection to test these initial APIs

##Swagger Integration

###Install Swagger Add gem “grape-swagger”, “0.7.2" to your Gemfile and bundle install

On your v1 base.rb, add the following:

add_swagger_documentation base_path: "/api”, api_version: 'v1', hide_documentation_path: true

Start the server again and go to /api/swagger_doc.json and you will see an automatic son description of the API generated by grape-swagger. You can also dig deeper and check out /api/swagger_doc/articles.json to see that grape-swagger describes all of your endpoints.

###Install Swagger UI Add gem “grape-swagger-rails” to your Gemfile and bundle install to set up the Swagger UI as a rails engine.

To mount the engine add the following in config/routes.rb

mount GrapeSwaggerRails::Engine => '/swagger'

Then create config/initializers/swagger.rb with the following contents:

GrapeSwaggerRails.options.url = 'swagger_doc.json'
GrapeSwaggerRails.options.app_url='/api'

Restart and go to http://localhost:3333/swagger and you will see the Swagger UI with the APIs

##Extending the API

###Optional parameters and validations ###Add relations to the Mongoid models