ruby-grape / ruby-grape/grape-swagger
Should not document examples for non-schema parameters
Nobody has claimed this yet.
- Dominant language
- Ruby
- Stars
- 1.1k
- Forks
- 479
- Avg merge
- 2d 14h
- Merged PRs (30d)
- 6
Description
As documented in the OpenAPI v2 spec, the example keyword only appears in schema objects and not parameter objects. If the example keyword appears in a parameter object, the OpenAPI validator returns the following error:
Structural error at paths./api/test
should NOT have additional properties additionalProperty: example
The root cause is that document_example adds the example keyword without check if the parameter is a schema/body type:
def document_example(settings)
example = settings[:example]
@parsed_param[:example] = example if example
end
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 locating the document_example method shown in the issue and inspect how parameter types are represented in @parsed_param. Reproduce the OpenAPI validator error for a non-schema parameter, then verify that example remains documented for schema/body parameters while being omitted elsewhere.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- ruby
- Domain
- api, documentation
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100