Don't overwrite model description with the route description. by Bhacaz · Pull Request #804 · ruby-grape/grape-swagger

Bhacaz · 2020-07-28T20:04:30Z

This PR have 3 features around the API response documentation.

Removing the assignation of the model description from route description. Some work was already started in this PR Corrected error in description of Models (definitions) #629.
Generate models documentation before the routes.
Add the ability to specified no model (or empty body).

1. Removing the assignation of the model description from route description.

I face the same problem explain in:

And I try to continued to resolved it.

Following the PR comments and the bug suggestion, the change in this PR will set a description to the model only if it doesn't have one and with a generic sentence.

2. Generate models documentation before the routes.

When I was generating my documentation I observe that sometimes Grape::Endpoint#response_object try to find the model definition without succeed with Grape::Endpoint#expose_params_from_model simply because the route documentation was generated before the model definition.

3. Add the ability to specified no model (or empty body).

The last thing I add was the ability explicitly set no model (or an empty body) in the response, for example in the failures. The problem was that when none is explicitly passed, Grape::Endpoint#response_object is really good to found a model from the path and add it to the documentation.

I hope it will be satisfying.

grape-bot · 2020-07-28T20:05:51Z

	1 Error
🚫	One of the lines below found in CHANGELOG.md doesn’t match the expected format. Please make it look like the other lines, pay attention to periods and spaces.

* [###](https://github.com/ruby-grape/grape-swagger/pull): Don't overwrite model definition with the route description. - [@Bhacaz](https://github.com/Bhacaz)

Generated by 🚫 danger

grape-bot · 2020-07-28T20:05:51Z

	1 Error
🚫	One of the lines below found in CHANGELOG.md doesn’t match the expected format. Please make it look like the other lines, pay attention to periods and spaces.

* [###](https://github.com/ruby-grape/grape-swagger/pull): Don't overwrite model definition with the route description. - [@Bhacaz](https://github.com/Bhacaz)

Generated by 🚫 danger

grape-bot · 2020-07-28T20:05:51Z

	1 Error
🚫	One of the lines below found in CHANGELOG.md doesn’t match the expected format. Please make it look like the other lines, pay attention to periods and spaces.

* [###](https://github.com/ruby-grape/grape-swagger/pull): Don't overwrite model definition with the route description. - [@Bhacaz](https://github.com/Bhacaz)

Generated by 🚫 danger

grape-bot · 2020-07-28T20:05:51Z

	1 Error
🚫	One of the lines below found in CHANGELOG.md doesn’t match the expected format. Please make it look like the other lines, pay attention to periods and spaces.

* [###](https://github.com/ruby-grape/grape-swagger/pull): Don't overwrite model definition with the route description. - [@Bhacaz](https://github.com/Bhacaz)

Generated by 🚫 danger

grape-bot · 2020-07-28T20:05:51Z

	1 Error
🚫	One of the lines below found in CHANGELOG.md doesn’t match the expected format. Please make it look like the other lines, pay attention to periods and spaces.

* [#804](https://github.com/ruby-grape/grape-swagger/pull/804): Don't overwrite model description with the route description. - [@Bhacaz](https://github.com/Bhacaz)

Generated by 🚫 danger

coveralls · 2020-07-28T20:08:32Z

Coverage increased (+0.003%) to 99.473% when pulling f6ac1b2 on Bhacaz:rework_on_response_object into 588579d on ruby-grape:master.

coveralls · 2020-07-28T20:08:32Z

Coverage increased (+0.003%) to 99.473% when pulling f6ac1b2 on Bhacaz:rework_on_response_object into 588579d on ruby-grape:master.

coveralls · 2020-07-28T20:08:32Z

Coverage increased (+0.003%) to 99.473% when pulling f6ac1b2 on Bhacaz:rework_on_response_object into 588579d on ruby-grape:master.

coveralls · 2020-07-28T20:08:32Z

Coverage remained the same at 99.47% when pulling 338513f on Bhacaz:rework_on_response_object into 588579d on ruby-grape:master.

LeFnord · 2020-09-02T22:12:41Z

yeap that does it 😄 … thanks @Bhacaz

please can you add an entry in UPGRADING.md with title: Upgrading to >= 1.3.0, thanks

Bhacaz · 2020-09-03T14:24:30Z

please can you add an entry in UPGRADING.md with title: Upgrading to >= 1.3.0

Sure!

Bhacaz · 2020-09-03T16:32:53Z

I needed to refactor lib/grape-swagger/doc_methods.rb to satisfy Rubocop (0.90.0)

LeFnord · 2020-09-03T20:41:48Z

lib/grape-swagger/endpoint.rb

-        next if value[:code] == 204
-        next unless !response_model.start_with?('Swagger_doc') && (@definitions[response_model] || value[:model])
+        # Explicitly request no model with { model: '' }
+        next if value[:model] == ''


mmh … ok … will have a look on it later, maybe it can be get together with no model key given

@LeFnord I did like that because by default if no model key is provided (line 219) the model use for the response will be the one returned by GrapeSwagger::DocMethods::PathString#build called here

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

Line 100 in 08b8c2f

@item, path = GrapeSwagger::DocMethods::PathString.build(route, options)

LeFnord · 2020-09-03T20:43:37Z

very good job, many thanks @Bhacaz

…rape#804)

Bhacaz force-pushed the rework_on_response_object branch 2 times, most recently from b200802 to a828ce0 Compare July 28, 2020 20:07

LeFnord approved these changes Sep 2, 2020

View reviewed changes

Bhacaz force-pushed the rework_on_response_object branch 3 times, most recently from c6cef6a to fc7b5b1 Compare September 3, 2020 15:42

Don't overwrite model description with the route destription.

338513f

Bhacaz force-pushed the rework_on_response_object branch from fc7b5b1 to 338513f Compare September 3, 2020 15:50

Bhacaz requested a review from LeFnord September 3, 2020 16:34

LeFnord reviewed Sep 3, 2020

View reviewed changes

LeFnord approved these changes Sep 3, 2020

View reviewed changes

LeFnord merged commit 565f8e9 into ruby-grape:master Sep 3, 2020

This was referenced Sep 3, 2020

Corrected error in description of Models (definitions) #629

Closed

Response Model Descriptions are incorrectly set and overwritten. #578

Closed

Bhacaz deleted the rework_on_response_object branch September 8, 2020 14:03

garyhtou mentioned this pull request Jul 9, 2022

Better API Documentation hackclub/hcb#2782

Closed

aka-momo pushed a commit to aka-momo/grape-swagger that referenced this pull request Feb 8, 2023

Don't overwrite model description with the route destription. (ruby-g…

149040b

…rape#804)

numbata pushed a commit to numbata/grape-swagger that referenced this pull request Dec 6, 2025

Don't overwrite model description with the route destription. (ruby-g…

0a08e60

…rape#804)

Conversation

Bhacaz commented Jul 28, 2020

1. Removing the assignation of the model description from route description.

2. Generate models documentation before the routes.

3. Add the ability to specified no model (or empty body).

Uh oh!

grape-bot commented Jul 28, 2020

Uh oh!

grape-bot commented Jul 28, 2020

Uh oh!

grape-bot commented Jul 28, 2020

Uh oh!

grape-bot commented Jul 28, 2020

Uh oh!

grape-bot commented Jul 28, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coveralls commented Jul 28, 2020

Uh oh!

coveralls commented Jul 28, 2020

Uh oh!

coveralls commented Jul 28, 2020

Uh oh!

coveralls commented Jul 28, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

LeFnord commented Sep 2, 2020

Uh oh!

Bhacaz commented Sep 3, 2020

Uh oh!

Bhacaz commented Sep 3, 2020

Uh oh!

LeFnord Sep 3, 2020

Choose a reason for hiding this comment

Uh oh!

Bhacaz Sep 8, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LeFnord commented Sep 3, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

grape-bot commented Jul 28, 2020 •

edited

Loading

coveralls commented Jul 28, 2020 •

edited

Loading

Bhacaz Sep 8, 2020 •

edited

Loading