Clarify Extensible name (with/without x-)

The javadoc of Extensible.addExtension states:

@param name the key used to access the extension object. Always prefixed by "x-".

This can be understood in two ways:

1. The name passed is plain and the extensible object will prefix it with x- in its map.
2. The name should start with x-. Does this mean other should be ignored?

In the TCK examples the annotations use names with the x- prefix already in the name. I’d think that from the user perspective these should be plain names without the x- as it is more readable and avoids using illegal names by design.

[EricWittmann]

We reviewed this issue in the MP hangout last week. The consensus was that we would not do any automatic conversion of non x- to x- extension names. However, we will ensure that the javadoc appropriately describes the requirements of using the @Extension annotation - specifically that the names of all extensions MUST begin with a x- or else an invalid document will be potentially created.

We have two main reasons for this.

1. Any consumers of the extension properties will need to refer to those properties with their proper x- prefixed names, so it would be weird to define them in @Extension without the prefix.
2. There are many ways to produce an invalid OpenAPI document using annotations, and it would be very difficult (perhaps impossible) for the platform implementation to check for every possible way in which the developer might mess up.

The best solution for this problem is for the platform to support validation of the resulting OpenAPI document. Optional validation support is something we will be adding to the MP+OAI spec in the near future.

[jbee]

There are many ways to produce an invalid OpenAPI document using annotations, and it would be very difficult (perhaps impossible) for the platform implementation to check for every possible way in which the developer might mess up.

With the same logic you could argue that static types in a language are “not needed” as developers have many ways (e.g. casts) to produce an invalid program. Why even have the compiler check it since there are many ways mess up, right?. Just saying.