Group API methods from multiple controllers

[johnnaegle]

I have two controllers that are related, each with a POST /create action, one with a GET /index action and one with a PUT /destroy action. The controllers use the same resource_id, which groups them together, but the generated documentation does not include all the methods.

The ideal grouping looks more like github's API documentation. The github API groups many different endpoints together under one resource, such as pull requests. The github API includes these (and more) endpoints under pull requests:

• GET /repos/:owner/:repo/pulls,
• PUT /repos/:owner/:repo/pulls/:number/merge ,
• PATCH /repos/:owner/:repo/pulls/:number

The routes in my project are

       api_pull_merges GET    /api/pulls/:pull_id/merges(.:format)                 api/pulls/merges#index
                       POST   /api/pulls/:pull_id/merges(.:format)                 api/pulls/merges#create
             api_pulls POST   /api/pulls(.:format)                                 api/pulls#create
              api_pull DELETE /api/pulls/:id(.:format)                             api/pulls#destroy

When the docs are generated only 3 of these appear in the generated api docs:

• GET /api/pulls/:pull_id/merges
• POST /api/pulls
• DELETE /api/pulls/:pull_id

The second post request is missing:

• POST /api/pulls/:pull_id/merges

The controllers:

class Api::PullsController < ApplicationController
  wrap_parameters false

  resource_description do
    name "Pull Requests"
    resource_id "Pull Requests"
    short "Manage pull requests"
  end

  api :POST, '/api/pulls', "Create a new pull request"
  def create
    head :ok
  end

  api :DELETE, '/api/pulls/:id', "Deletes a pull request"
  param :id, Integer, :required => true, :desc => "Which PR to nuke"
  def destroy
    head :ok
  end
end

class Api::Pulls::MergesController < ApplicationController
  wrap_parameters false

  resource_description do
    resource_id "Pull Requests"
  end

  api :GET, "/api/pulls/:pull_id/merges", "List merges for a PR"
  param :pull_id, Integer, :required => true
  def index
  end

  api :POST, "/api/pulls/:pull_id/merges", "Merge a pull request"
  param :pull_id, Integer, :required => true
  def create
    head :ok
  end

end

Sample project here: https://github.com/johnnaegle/apipie-example.

git clone https://github.com/johnnaegle/apipie-example
cd apipie-example
bundle install
rake apidocs:regenerate
open public/docs/api.html

Is there a way to group actions from multiple controllers into a high level resource grouping?

[johnnaegle]

From what I can see, the methods are grouped by resource_description and method name and the controller/route information isn't used. By putting two controllers in the same "resource description" their method names clash here:

lib/apipie/resource_description.rb

    def add_method_description(method_description)
      Apipie.debug "@resource_descriptions[#{self._version}][#{self._name}]._methods[#{method_description.method}] = #{method_description}"
      @_methods[method_description.method.to_sym] = method_description
    end

the @_methods hash would need to consider the controller, or there needs to be a new concept, a resource_description_group that can put resource descriptions together

[itskingori]

See fix in https://github.com/Apipie/apipie-rails/issues/455#issuecomment-268555114.