ruby-grape / ruby-grape/grape-swagger

Question: base_path included in Path object

Open
#552 7 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

question
Dominant language
Ruby
Stars
1.1k
Forks
479
Avg merge
2d 14h
Merged PRs (30d)
6

Description

Have a question around the 'Path' object for individual endpoints.

The grape setup is similar to the one in api_swagger_v2_global_configuration_spec

module TheApi
  class ConfigurationApi < Grape::API
    format :json
    prefix: 'somewhere/over/the/rainbow'
    version 'v3', using: :path

    desc 'This returns something',
    get :something do
      { 'something' => :foo }
    end

    add_swagger_documentation format: :json,
                              base_path: -> { 'somewhere/over/the/rainbow' },
                              add_base_path: true,
end

Reading the Swagger specification for path objects and the description for the Path Item Object

A relative path to an individual endpoint

I would expect the doc to have the output of this:

{"info"=>{"title"=>"API title"},
 "swagger"=>"2.0",
 "produces"=>["application/json"],
 "host"=>"another.host.com",
 "basePath"=>"somewhere/over/the/rainbow",
 "schemes"=>["http"],
 "tags"=>
  [{"name"=>"configuration",
    "description"=>"Operations about configurations"}],
 "paths"=>
  {"/v3/configuration"=>
    {"get"=>
      {"summary"=>"This returns something",
       "description"=>"This returns something",
       "produces"=>["application/json"],
       "tags"=>["configuration"],
       "operationId"=>"getSomewhereOverTheRainbowV3Configuration"
}}}}

vs. the current one of

{"info"=>{"title"=>"API title"},
 "swagger"=>"2.0",
 "produces"=>["application/json"],
 "host"=>"another.host.com",
 "basePath"=>"somewhere/over/the/rainbow",
 "schemes"=>["http"],
 "tags"=>
  [{"name"=>"configuration",
    "description"=>"Operations about configurations"}],
 "paths"=>
  {"/somewhere/over/the/rainbow/v3/configuration"=>
    {"get"=>
      {"summary"=>"This returns something",
       "description"=>"This returns something",
       "produces"=>["application/json"],
       "tags"=>["configuration"],
       "operationId"=>"getSomewhereOverTheRainbowV3Configuration"
}}}}

Or is there any other way to achieve this without changes to the current code?
Or am I misinterpreting the spec?

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 with spec/swagger_v2/api_swagger_v2_global_configuration_spec.rb, which the issue uses as its setup, and compare the generated paths with the Swagger Path Item Object expectation described here. Trace how base_path and the endpoint prefix are represented, then add or update a focused specification so the intended path output is explicit and passing.

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
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.