ruby-grape / ruby-grape/grape-swagger
Can't override documentation for old route
Nobody has claimed this yet.
- Dominant language
- Ruby
- Stars
- 1.1k
- Forks
- 479
- Avg merge
- 2d 14h
- Merged PRs (30d)
- 6
Description
module TheApi
class NamespaceApi < Grape::API
version [:v1, :v2]
namespace :hudson do
desc 'old document', deprecated: true
get '/' do
{ data: 'old_data' }
end
end
end
class CascadingVersionApi < Grape::API
version :v2
namespace :hudson do
desc 'Document root. Cannot see it. see only old version'
get '/' do
{ data: 'new_data' }
end
desc 'This path os ok in docs'
get '/other_path' do
{ data: 'new_data' }
end
end
end
class TagApi < Grape::API
prefix :api
mount TheApi::CascadingVersionApi
mount TheApi::NamespaceApi
add_swagger_documentation
end
end
I have 2 versions of api, and the same route. From grape prospective it works fine - it returns data according to api version. But in documentation I see only description for first version, which is deprecated. And it's marked as deprecated - and it's bigger issue. Endpoint, which is okay marked as deprecated.
Is it an issue or is it any way to mark new version of route to show it correctly in docs?
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 two-version route and generated documentation from the Ruby example in the issue. Inspect how the mounted APIs choose documentation for identical paths and verify that the v2 route uses its own description and is not marked deprecated; done when the generated docs distinguish the old and new route metadata correctly.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- ruby
- Domain
- api, documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100