No commit activity in last 3 years
No release in over 3 years
Provides a simple DSL to describe your JSON API, and let's you mount an interactive sandbox to explore and test it.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies
 Project Readme

rails_api_explorer

Provides a simple DSL to describe your JSON API, and let's you mount an interactive sandbox to explore and test it.

Here's a demo.

Gem Version

Installation

Add this line to your application's Gemfile:

gem 'rails_api_explorer'

And then execute:

$ bundle

Usage

Describe your API

Describe your API in config/initializers/api_explorer.rb:

ApiExplorer.describe do
  base_url 'http://localhost:3000/api/'

  shared do
    header 'X-AUTH-TOKEN', source: { request: "POST:users/sign_in", accessor: "['auth_token']"}
    # The source option makes the value get set automatically when a request to the given url succeeds.
    # The accessor is evaluated on the JSON object returned by the server.
  end

  post 'users/sign_in' do
    desc "Authenticate a user, returns the auth token. Anything except blank values will work for this example."

    exclude_shared_header 'X-AUTH-TOKEN'

    struct 'user_login' do
      string 'email'
      string 'password'
    end
  end

  group "Posts" do
    get 'posts'

    get 'posts/:id' do
      desc "Returns details for a single post."
    end

    post 'posts' do
      desc "Create a post."
      struct 'post' do
        string 'title', desc: "Required."
        string 'body'
      end
    end

    patch 'posts/:id' do
      struct 'post' do
        string 'title', desc: "Required."
        string 'body'
      end
    end
  end
end

Then mount it in your routes.rb:

mount ApiExplorer::Engine => '/api/explore', as: 'api_explorer'

Access control

If you don't want the public to access the explorer, you can provide a lambda that will be executed in the before_filter of the controller:

ApiExplorer.auth = lambda do
  authenticate_user!
  current_user.admin? or redirect_to main_app.root_path
end

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request