AsyncAPI 3.x: publish a message's example, some of the time

[LautaroPetaccio]

Thirteenth in the AsyncAPI stack, on top of #1753. Draft, like the two below it.

Why

A message's examples are what the document's author knows the service accepts. A service that silently drops what it does not recognise — the normal behaviour of a Kafka consumer or a WebSocket handler faced with a malformed message — may never reply to a payload sampled from the schema alone, and a search that never sees a reply never gets to tell the reply variants apart. Publishing the author's example some of the time is the cheapest way to make sure the search starts from something that works.

What it does

With --probAsyncApiExamples p (@Experimental, @Probability, 0 by default), the first example of a message is offered as a whole value beside the schema-derived genes, chosen with probability p when the message is sampled. Same for a headers example, minus the field the correlation id is stamped into, which the headers gene does not have either.

How — no new machinery

REST already turns a schema's example into a ChoiceGene between the example and the schema-derived genes, at probUseExamples. So the example is put on the message's own copy of the payload schema before it goes to RestActionBuilderV3.createGeneForDTO, and that machinery does the rest. Ten lines in AsyncApiGeneBuilder, one line in options().

Two limits, both stated in the code:

• Only the first example. The genes are built through an OpenAPI 3.0 wrapper, and swagger-parser drops the plural examples on a 3.0 schema — checked empirically, not assumed; the singular example survives. A TODO says where to pass them all once the builder can take them. In the corpus, every message with examples has exactly one.
• Object payloads only. The builder attaches a deprecation warning to example on a non-object schema, and that would reach the user as a complaint about a document that is in order.

The TODO this resolves in AsyncApiSampler is removed.

Testing

AsyncApiGeneBuilderTest (+5): the Scalar PlanetCreated example published whole when asked for every time; nothing changing shape when not asked; a scalar payload left alone; a headers example losing the correlation field; only the first of two examples used. AsyncApiSamplerTest (+1): through the sampler with --probAsyncApiExamples=1.0, the payload of a sampled action is the author's example.

All AsyncAPI suites plus the config ones: 199 tests, 0 failures.