Supporting example and nullable (not just vendor prefixed)

[philsturgeon]

Issue #112 asks for x-nullable, but this asks for another feature.

Dropping requirement for the vendor prefix of x-nullable and x-example.

Currently I can either use Dredd or ReDoc, I cannot use both. If I use example: stuff for foo property, then ReDoc will render it, but Dredd will error due to unexpected property.

When I switch to using x-example, ReDoc will fail and default to shoving string into the examples, making humans sad reading the docs.

I'm trying to write a PR for x-example support in ReDoc as they already have an issue for it, but... double attack.

[kylef]

The reason the Swagger adapter (and in turn Dredd) will produce an error, is because the example keyword is not permitted in this area in the Swagger specification.

The official Swagger JSON Schema (https://github.com/OAI/OpenAPI-Specification/tree/master/schemas/v2.0) will not permit unknown keys and therefore the example has to be an extension. We are validating the source document using the official schema which is causing the error.

I do not think there is anything we can do here other than add support for x-example in ReDoc.

[philsturgeon]

RE ReDoc: Already trying to PR them but getting stuck on the first step. Redocly/redoc#304

As for following the spec exactly: I figured that would be the case. Some folks use OpenAPI Sampler to backport some of these OpenAPI v3.0 features into their v2.0 tooling. This helps alleviate the pain of required stuff being in v3.0 and not in v2.0, and stops everything being almost useless in the mean time.

That said, v3.0 is so close, I'll just keep going with the ReDoc approach. Thank you.

[kylef]

Seems that ReDoc is adding support for x-example (Redocly/redoc#186 (comment)), we have #112 to track adding x-nullable support. I think we can close this issue.

[philsturgeon]

Thank you :)