ruby-grape / ruby-grape/grape-swagger
Detail mixes into adjacent route definition
Nobody has claimed this yet.
- Dominant language
- Ruby
- Stars
- 1.1k
- Forks
- 479
- Avg merge
- 2d 14h
- Merged PRs (30d)
- 6
Description
In desc method, I found the detail definition will be integrated into response entity description. And what's worse, it will contaminate following route definition, which leads to using above detail content. The following code can show it:
resources :students do
desc 'Create a student',
summary: 'Create a student',
detail: 'This is detail for post api.',
entity: Entities::Student
post '' do
end
desc 'List users',
summary: 'List users',
detail: 'This is detail for get api.',
entity: Entities::Student
get '' do
end
end
And the get api render the doc is below, noticing the entity description:

Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing the nested resources example using desc with detail and entity, then trace the route documentation generation that handles those definitions. Done means the POST detail remains attached to the POST route, the GET detail remains attached to the GET route, and neither detail appears in the entity description or contaminates the following route.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- ruby
- Domain
- api, documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 50/100