ruby-grape / ruby-grape/grape-swagger
Question: base_path included in Path object
Nobody has claimed this yet.
- 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
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 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