Media type in OpenAPI

[thekaveman]

UPDATE

See comment below https://github.com/openmobilityfoundation/mds-openapi/issues/34#issuecomment-1534066482

Original

MDS defines the media type application/vnd.mds+json for use in the (response) Content-type header, and for the purposes of version negotiation whereby a client could request a particular version:

Accept application/vnd.mds+json;version=2.0

The OpenAPI endpoints thus far have used application/vnd.mds+json as the Content-type and not required it as an Accept header.

[thekaveman]

It seems like there is no way to distinguish the two (Accept vs. Content-type) in OpenAPI 3.1 or earlier.

Each Media Type Object defines both the request and response media type.

@schnuerle -- which should we use in the MDS OpenAPI docs?

• application/vnd.mds+json is what the spec says it should be, but...
• application/json renders much nicer in the Stoplight website, giving an immediate preview vs. having to click to "Send request" with the above type

As application/vnd.mds+json

Here we see a "Send request" link

Clicking that (sometimes) gives a preview

As application/json

Here we immediately see a preview without clicking any buttons ("Send request" is still available)

[schnuerle]

Ah I prefer the application/json render and I think it makes sense for this work to use that.

[thekaveman]

Great, that's what I went with!