ruby-grape / ruby-grape/grape-swagger

Can't override documentation for old route

Open
#678 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.