Operations parameters performance issues.

[antek-drzewiecki]

When having an Api with several operations, its possible that the total parameters tend to grow. When you have kramdown markup enabled its possible that the endpoint response tend to become drastically slow. I currently have a case where my endpoint consist of 19 operations with a total of 72 parameters and kramdown enabled. The current benchmarks are:

      user     system      total        real
   3.170000   0.030000   3.200000 (  3.210574)

It takes about 3 seconds to load down one single endpoint. Upon disabling kramdown these are the following specs.

      user     system      total        real
   0.160000   0.000000   0.160000 (  0.156400)

This is quite acceptable but the notes and documentation do not get formatted at all.
I noticed that parameter description are formatted as well. In my opinion majority of the cases would not use formatted parameter descriptions. Descriptions consists of mostly single lines. And there might be some edge cases where you want your description italic. Upon disabling markdown for descriptions the specs are:

  user     system      total        real
   0.870000   0.000000   0.870000 (  0.886495)

In my opinion this is more acceptable. There are 3 kind of options what we could do to improve the speed when markdown is enabled.

1. Remove markdown upon descriptions, it isn't documented that means less people know it.
2. Add options to the type of markdown you want.
   • markdown: :all ( would mark down everything)
   • markdown :none ( would mark down nothing)
   • markdown :notes (would only mark down notes)
3. Remove the kramdown gem and add redcarpet instead. See benchmark specs. But this would have a major effect on the gem itself..

This topic is open for discussion.

[dblock]

I think Redcarpet is a valuable improvement if all it does is improve speed. Another one would be to "compile" things so that you only spend time rendering the first request.

[antek-drzewiecki]

I have benchmarked the parameter description formatting and it adds about 0.15 seconds execution time for a single parameter. Pre processing the markdown would add extra logic and complexity since it needs to be done when the application starts. Also you would not be able to use lambda's to update description dynamic (if you would like). But it's a good idea.

@dblock well it is not that simple. Redcarpet has other markdown features then kramdown has. So basically you would have a slightly different syntax and features depending on the modules you include.

A different idea is to configure your favoruite markdown provider like jekyll does or trough a adapter pattern. But then the question is, should this gem be really focusing on markdown.

[dblock]

I think when Kramdown was added the decision wasn't made very purposefully, it was like "lets add some markdown support". Either way, it's weird that it's so slow, maybe you can dig into that? I would accept any PR that's an improvement.

[antek-drzewiecki]

I couldn't find out why my Api became that slow. I benchmarked a bit more in irb, kramdown is much faster in there, but still slower then redcarpet.

But I'm almost ready with the implementation. Ill have a pull request soon where you can specify your favourite markup tool. Configuring none markup adapter will render the text as plain text. I removed any markup dependency from grape-swagger.

Grape-swagger comes now with standard adapters for Redcarpet and Kramdown. Users can plug their own adapter in for their markup tool, which has to implement a specific method to render the text.

Usage will be in your application:
Gemfile:

gem 'kramdown'

or

gem 'redcarpet'
gem 'rouge'

And in your code:

module API
  class Root < Grape::API
    mount API::Cats
    mount API::Dogs
    mount API::Pirates
    add_swagger_documentation(markdown: GrapeSwagger::Markdown::RedcarpetAdapter.new({options...})

    add_swagger_documentation(markdown: GrapeSwagger::Markdown::KramdownAdapter.new({options...})
  end
end

Adapters have the responsibility to require the missing dependencies. And to raise errors if dependencies are not installed.

[dblock]

I think we can close this given #142.