Bryan Mytko

Software and stuff.

Extracting API Pie

July 17, 2015

Apipie (github) is an amazing Rails engine that lets you document your APIs in the code using Apipie's DSL. It's super simple to set up -- just install the gem and start describing the APIs in your controller:

1
2
3
4
5
6

api :GET, '/posts/:id'
param :id, Integer, required

def show
  #whatever
end

The problem is that once you start adding multiple actions with lots of parameters, things get messy. Your controllers wind up bloating to hundreds of lines, and having all this extra code in there can be extremely distracting. It starts to feel like maybe this code doesn't exactly belong there. Luckily enough, it's easy to extract the Apipie code into its own clean and organized module.

First we can set up a file apipie_descriptions.rb in the /lib directory.

1
2

module ApipieDescriptions
end

Then we can set up files for each of our controllers in the same directory. In this example we'll assume we have APIs for users and posts.

users.rb

1
2

module ApipieDescriptions::Users
end

Then we'll extend ActiveSupport::Concern and include them in the main module as class methods.

1
2
3
4
5
6
7
8

module ApipieDescriptions
  extend ActiveSupport::Concern

  module ClassMethods
    include ClassMethods::Users
    include ClassMethods::Posts
  end
end

We can put all of our Apipie logic in these files now, and simply include this module in our controllers. Note that because of the way the DSL is designed, we need to clear each method when we're done with it so that Apipie knows that we're done defining the documentation for that action.

E.g.,

lib/apipie_descriptions/users.rb

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

module ApipieDescriptions::Users
  def apipie_users_index
    api :GET, "/users", "Returns a collection of users"
      description <<-EOS
      If successful, it returns a collection of <tt>users</tt>,
      with status <tt>200</tt>.
    EOS
    apipie_clear(__method__)
  end

  def apipie_users_show
    api :GET, "/users/:id", "Returns a user"
    description <<-EOS
      If successful, it returns a <tt>user</tt>,
      with status <tt>200</tt>.
    EOS
    apipie_clear(__method__)
  end
end

app/controllers/api/v1/users_controller.rb

1
2
3
4
5
6
7
8

module Api::V1
  class UsersController < ApiController
    include ApipieDescriptions

    apipie_users_index
    apipie_users_show
  end
end

And that's all there is to creating well-documented APIs without cluttering up your codebase.