Affects Version/s: CN01
Fix Version/s: CN02
ODATA-884 currently specifies a "CustomParameterExampleValue" for providing a sample value for a custom parameter within an HttpRequest annotation.
More generally, OpenAPI supports defining one or more sample values for each parameter and each (valid media type allowed for a) request or response payload (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#example-object), as well as a single example for each schema object (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#schema-object).
OpenAPI also supports the example value either being an (inline or referenced) Value, or an ExternalValue, where ExternalValue is an external reference to the literal value in a native (i.e., non-OpenAPI) format. This is done partially to support non-JSON media type values, but can also be useful for referencing external samples. We could support this by defining a base "Value" type and inherited "InlineValue" or "ExternalValue" types.
We could support this by allowing a new "ExampleValue" annotation on a type, parameter, or for a request or response body within an HttpRequest.
And, within HttpResponse:
<Property Name="Example" Type="Core.ExampleValue"/>
1) OpenAPI supports the Description as CommonMark syntax (http://spec.commonmark.org/) for rich text representation. We could support this as well.
2) OpenAPI also includes a short "Summary"
3) OpenAPI supports multiple examples for request/response bodies and parameters, but not for schema objects (i.e., types). It's unclear how you would relate individual request examples with individual response examples.