While using the API Blueprint formatter, I discovered that this gem will always group your endpoint documentation by route no matter what. This isn't always desirable as some users may want to have a bit more control over how these requests are grouped in documentation.

I attempted to write specs:

route '/resource/:id', 'Read Resource' do
  get 'fetch resource with specified id' do
    #...
  end
end
route '/resource/:id', 'Update Resource' do
  patch 'update resource with specified id' do
    #...
  end
end

as

get '/resource/:id' do
  #...
end
post '/resource/:id' do
  #...
end

But the test suite will fail with --format RspecApiDocumentation::ApiFormatter format because no route_uri is set.

I would think that these requests would only be grouped together when they are in the same route block but that is not the case. I attempted to adjust functionality to work like that but didn't get very far.

How would you feel about a change like this??? If you want multiple endpoint groupped together they must all have the same route_uri, route_optionals, and route_name?

This means that you can group endpoints as follows

route '/resource/:id', 'Read Resource' do
  get 'fetch resource with specified id' do
    #...
  end
end
route '/resource/:id', 'Modify Resource' do
  patch 'update resource with specified id' do
    #...
  end
end
route '/resource/:id', 'Modify Resource' do
  delete 'delete resource with specified id' do
    #...
  end
end

This will put the get call into it's own "Read Resource" group and the patch/delete calls into their own "Modify Resource" group.

Another options would be to set something like a "route id" or some kind of unique identifier on the example options somewhere around here.

Thoughts? I have no issue updating documentation once we agree on an approach.