Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Pipeline Gem Version

Grape Starter

Is a tool to help you to build up a skeleton for a Grape API mounted on Rack ready to run. grape-swagger would be used to generate a OAPI compatible documentation, which could be shown with ReDoc.

ReDoc demo

Why the next one?

  • build up a playground for your ideas, prototypes, testing behaviour … whatever
  • no assumtions about you can choose, if you want to use a backend/ORM, ergo no restrictions, only a pure grape/rack skeleton with a nice documentation


Install it

$ gem install grape-starter

Create a new project

$ grape-starter new awesome_api

with following options:

-f, --force                # overwrites existend project
-p foobar, --prefix=foobar # sets the prefix of the API (default: none)
-o sequel, --orm=sequel    # create files for the specified ORM, available: sequel, activerecord (ar) (default: none)

This command creates a folder named awesome_api containing the skeleton. With following structure:

├── <Standards>
├── api
│   ├── base.rb        # the main API class, all other endpoints would be mounted in it
│   ├── endpoints      # contains the endpoint file for a resource
│   │   └── root.rb    # root is always available, it exposes all routes/endpoints, disable by comment it out in base.rb
│   └── entities       # contains the entity representation of the reource, if wanted
│       └── route.rb
├── config             # base configuration
│   └── …
├──          # Rack it up
├── lib                # contains the additional lib file for a resource
│   ├── models
│   │   └── version.rb
│   └── models.rb
├── public             # for serving static files
│   └── …
├── script             # setup / server / test etc.
│   └── …
└── spec               # RSpec
    └── …

… using --orm flag adds follwing files and directories to above project structure:

├── .config
├── config
│   …
│   ├── database.yml
│   └── initializers
│       └── database.rb
├── db
│   └── migrations

Don't forget to adapt the config/database.yml to your needs and also to check the Gemfile for the right gems.

In .config the choosen ORM would be stored.

To run it, go into awesome_api folder, start the server

$ cd awesome_api
$ ./script/server *port

the API is now accessible under: http://localhost:9292/api/v1/root the documentation of it under: http://localhost:9292/doc.

More could be found in README.

Add resources

$ grape-starter add foo [http methods]

This adds endpoint and lib file and belonging specs, and a mount entry in base.rb.

Using it with following options:

-e, --entity    # a grape entity file will also be created
-m, --migration # adds also a migration file, if an ORM is used
-o, --orm       # sets the parent class of libe file (e.g: `Foo < Sequel::Model` for Sequel)

to add CRUD endpoints for resource foo. By given http methods only this one would be generated. For available methods see: Templates::Endpoints.


grape-starter add foo post get

will use post and get_one to create the post and get endpoint, it would be respected, if it is the singular or plural form of it, so the plural form would look like:

grape-starter add foos post get

this will use post, get_all and get_specific to create the post, get and get :id endpoints.

If the orm switch true, the lib class would be created as child class of a specific ORM class, so for example for Sequel, it would be wirtten: Foo < Sequel::Model instead of Foo, hereby the using ORM would be taken from the configuration, which was stored by project creation.

Import OAPI spec [WIP]

$ grape-starter import path/to/spec

to create an API based on the spec.

To Dos:
  • read spec an create per namespace a file with defined endpoint
  • read path parameter
    • requires it in param block
    • specify it
  • handle query parameter -> check it
  • handle body parameter -> check it
  • add description block

Remove a resource

$ grape-starter rm foo

to remove previous generated files for a resource.


Any contributions are welcome on GitHub at

Adding a new ORM template

To add an new ORM, it needs following steps:

  1. A template class, with predefined methods …
module Starter
  module Templates
    module <YOUR NAME>
      def model_klass
        # the class, from which self inherit, e.g. 'Sequel::Model'

      def initializer
        # provide your string

      def config
        # provide your string

      def rakefile
        # provide your string

      def gemfile
        # provide your string

see as example sequel.rb, there the return value of each method would be written into the corresponding file (see: orms.rb).

  1. An additional switch in the and Starter::Names.lib_klass_name methods to choose the right template.
  2. An entry in the description of the new command, when it would be called with -h


The gem is available as open source under the terms of the MIT License.