Use x-example for non-body parameters

[olivier-thatch]

OpenAPI 2.0 does not support setting example for non-body parameters. The x-example extension is commonly used instead and is understood by most OpenAPI tooling including Swagger UI and Swagger Converter (which will convert x-example to example, since that works in OpenAPI 3.0).

Today one can work around this by setting documentation: { x: { example: "foo" } } for non-body parameters, however the inconsistency between documentation: { example: "foo" } and documentation: { x: { example: "foo" } } is annoying, and it's also problematic if you want to share params between e.g. a GET endpoint (which will use query parameters by default) and a POST endpoint (which will use body parameters by default).

This PR makes is so that documentation: { example: "foo" } can be used in all places, and grape-swagger will automatically convert the examples for non-body parameters to be rendered as x-example in the generated schema.

References:

• https://swagger.io/docs/specification/v2_0/adding-examples/
• https://help.apiary.io/api_101/swagger-extensions/#x-example
• https://github.com/swagger-api/swagger-parser/blob/28bf368a878bc8839dcfc180820f7b1b8d488a60/modules/swagger-parser-v2-converter/src/main/java/io/swagger/v3/parser/converter/SwaggerConverter.java#L770-L773

[olivier-thatch]

I don't know why tests are failing. The failures do not look related to the code changed in this PR, and I cannot reproduce the failures locally.

[numbata]

Hi @olivier-thatch,
I've been able to reproduce the failed test with the following commands:

MODEL_PARSER=grape-swagger-entity bundle install
MODEL_PARSER=grape-swagger-entity bundle exec rspec spec/swagger_v2/api_swagger_v2_type-format_spec.rb:87

For now, I can confirm that these failures do not seem to be related to the code changed in this PR. I will be looking closely into the issue. If you'd like to investigate these unrelated failures as well, please let me know.

[numbata]

Just a heads-up, I've identified the cause of the failing test and have opened a PR (ruby-grape/grape-swagger-entity#82) to address it. The issue with red specs absolutely is not related to the changes in this PR.

[olivier-thatch]

@numbata Thanks! I will rebase once your PR is merged.

[olivier-thatch]

@numbata Tests are passing now!

[numbata]

Cool! It looks like this should also solve #884 and supersede #885.

[olivier-thatch]

Hm. I'm not sure why this PR is now causing segfaults with Ruby 3.5-dev 🤔

[dblock]

I fixed CI on master, rebase please?

[numbata]

Thanks for the rebase, @olivier-thatch! Could you add a CHANGELOG entry? Once that's in, we'll squash and merge this PR into master.

[numbata]

#951 (comment)
it wants a period in the end of the line.

[numbata]

@olivier-thatch Fantastic work on this PR! 👍
@dblock It looks ready to merge when you have a moment.

[dblock]

LGTM, @LeFnord is usual maintainer here, tagging him but will merge if we don't hear back in a bit

[LeFnord]

@dblock … will do it on sunday, but feel free to to merge it, if you think it is urgent

[LeFnord]

Thanks @olivier-thatch …
Do we want an documentation entry, so this feture is known?
no, don't think so … will merge it