Examples in a cURL-like format, preferably at the PathItem Object

[jeremyfiel]

Something I've been pondering recently is how to provide an example of an api request in a format similar to how one might find it out in the wild while playing with an api client or cURL. Particularly, because we don't have a great way to define header values and their parameters, it's very difficult to deliver a message to a developer for how a request should be composed. related: #3827

I suppose you could just use an externalValue to a file in .http or .md to represent that. But, considering most doc UI's will not parse an externalValue for view, can we find a better way to represent that? The other reason is the externalValue keyword is only available at requestBody XOR responseBody, I want to represent the full example.

This could possibly be something for the Arazzo Specification to consider. @frankkilcommins

The glaring omission is an Examples object at the PathItem Object to bring together both the request and response bodies.

This is a sample of what I would like to document.

POST /thing HTTP/1.1
accept: application/json; charset=utf8; q=0.9, text/plain; charset=utf8; q=0.8
authorization Bearer XXX
content-type: application/json; charset=utf8
content-length: 50
x-custom-header: thing; some_param=some_value
prefer: respond-async; wait=10

{ ... }
---
202 Accepted HTTP/1.1
content-type: application/json; charset=utf8
content-length: 500
link: <uri>; rel="/status-monitor"

{ ... }

[handrews]

@jeremyfiel This would really be great to do over in the learn repository. With the new patch releases, we link to the Learn site in the introduction.

Adding examples to the spec right now is an extremely heavy lift: We're already well over capacity for what the team can review and improve, and we need to actually ship 3.0.4 and 3.1.1. But there's no complex timing to add things to the learn site, and we just agreed to consolidate examples on that site.

Would you be amenable to moving this discussion over there? (It might need to convert to an issue as I'm not sure we have discussions enabled there, but I'll sort it out if you're OK with moving it).