Failing to use description for summary when neither detail nor summary are provided

[radanskoric]

Right now, if an endpoint doesn't declare anything beyond the default desc value, the summary field will be empty.

I.e. if this is done:

desc 'A short endpoint description'
get '/endpoint' do
end

The swagger documentation for this endpoint will not contain the summary field. This is a problem because if you then render using something like Swagger UI the resulting rendering will not contain any short description, the line will have just the url, like this:

This seems to me like undesirable behaviour since the endpoint would look more informative if it used the desc value as summary.

This behaviour is right now encoded in specs, although indirectly. There are many specs but one of the simpler cases is in the mounted_target_class_spec which declares an endpoint with just desc but then doesn't expect any summary in the result.

I have a hunch that it didn't used to be like this since the code tries to read the desc attribute of route options and use it as summary but current version of grape never sets that attribute anywhere in the code.

Is this really desirable behaviour or a bug?

[dblock]

I am surprised desc is not used! So I think you should try a PR that fixes this.

[radanskoric]

Great, thanks!

I'll prepare a PR when I find a bit of time. The general idea is to basically just use description if there is no summary option on the route. Does that make sense to you?

The fix is simple, most of the change will be updates to all the specs indirectly encoding this behaviour
in the expected output.

[arseny-emchik]

It looks like it depend on detail option in desc block.
For example:

          desc 'Some subscriptions' do
            params some
            success some
          end

          desc 'Some subscriptions' do
            detail ""
            params some
            success some
          end

So it works if detail option was provided. Even if detail option was blank.

Maybe this will help.

[arseny-emchik]

@radanskoric
I've just looked through the code of the gem.
So It looks like a bad UI/UX, but not a bug.

1. There is no option desc. So this line of code will never be executed:
   

   grape-swagger/lib/grape-swagger/endpoint.rb

   Line 142 in 02ede02

   summary = route.options[:desc] if route.options.key?(:desc)

2. grape-swagger/lib/grape-swagger/endpoint.rb

   Line 143 in 02ede02

   summary = route.description if route.description.present? && route.options.key?(:detail)

   - This mean that they show description only if there are additional details. So if you provide details, your description will be shown like a summary. Otherwise you need to open tab and see into it. Your description will be marked as implementation notes or something like that. You can see it in the line

   grape-swagger/lib/grape-swagger/endpoint.rb

   Line 150 in 02ede02

   description = route.description if route.description.present?

[radanskoric]

You're right, that it is the issue. I called it a Bug because I view it as undesirable behaviour. Showing nothing when there are additional details missing doesn't make much sense to me. We have a useful summary present so it should be used.