Adding to an existing application

So you already have an existing application. Awesome!

Do this stuff:

gems

Add to your gemfile and bundle install:

gem 'grape' # Another big part of this
gem 'doorkeeper', '~> 2.2.2' # A big part of this.

# Basic requirements
gem 'haml' # All the view files are in haml
gem 'bootstrap-sass', '~> 3.3.1' # All the views are styled with bootstrap
gem 'kaminari' # Pagination - could be will_paginate instead

# Grape extensions
gem 'wine_bouncer' # Authentication, adds swagger documentation
gem 'api-pagination' # API pagination. Relies on kaminari or will_paginate being present
gem 'grape-swagger' # Adds swagger documentation to grape

# Swagger UI
gem 'swagger-ui_rails' # Add swagger-ui assests to asset pipeline
gem 'kramdown' # Swagger-ui markdown parser
gem 'rack-cors', :require => 'rack/cors' # Make Swagger spec CORS, required!

config files

Add the CORS middleware to your config/application.rb, so that swagger-ui can access your API - link:

config.middleware.insert_before "ActionDispatch::Static", "Rack::Cors" do
  allow do
    origins '*' # Permit CORS from any origin, only in the API route
    resource '/api/*', :headers => :any
  end
end

1. Create a file at config/initializers/doorkeeper.rb and copy this.

• This is based on devise - if you aren't using devise, you'll have to set your own resource_owner_authenticator block
• Configure your own OAuth scopes (e.g. not :read_user and :write_user). They are declared as constants in the doorkeeper config so 1. they're defined only once, and 2. are accessible everywhere in the application

2. Add a config/initializers/wine_bouncer.rb file, copying this.

3. Add the swagger-ui documentation assets to your config/assets.rb file - link

4. Add this to your routes:

use_doorkeeper # doorkeeper
mount API::Base => '/api' # Grape

resources :documentation, only: [:index] do # swagger-ui
  collection do # documentation token redirect
    get :o2c
    get :authorize
  end
end

grape

Copy app/controllers/api into your app.

This mounts grape in the way recommended by Monterail in Introduction to building APIs with Grape (and part 2 of the series which discusses setting up logging). It's a good way of doing it.

swagger-ui

Copy -

• the views (all files from):
  • app/views/documentation
• the controller:
  • app/controllers/documentation_controller.rb
• the styles:
  • app/assets/stylesheets/documentation.css.scss
• the javascript:
  • app/assets/javascripts/documentation.js and
  • app/assets/javascripts/inlined_swagger.coffee

=======

Optional parts that are still a good idea:

dot-env for configuration, because it's awesome.

specs:

Move the controllers/api folder to your project for the current user specs and the swagger spec.

Move the controller/documentation_controller_spec.rb for the documentation controller.

Add convenience methods for generating a working doorkeeper app, for integration testing of the API - spec/spec_helper.rb

serializers

If you want to use active model serializers (sample serializer in app/serializers/item_serializer.rb), you need to add these two gems to the gemfile:

gem 'active_model_serializers'
gem 'grape-active_model_serializers'

And then add require 'grape-active_model_serializers' to the top of your config.ru file.