Improvements for links in v4

[mikekistler]

I've put together a proposal for reworking/extending support for links in OASv4/Moonwalk.

https://gist.github.com/mikekistler/1983a8249c0df56a46f94b4df1b7181d

I'd be happy for feedback on this.

[ahl]

What is the purpose of links? How are they currently used, and how would they be ideally be used if shortcomings were removed?

I have seen them as interesting documentation addenda, but nothing that couldn't be equally well-expressed in, say, the description field for an operation.

[graipher]

Links are machine-readable, in contrast to the description which at best would use some convention.

Links are used by tools such as

• graphql-mesh to generate & run GraphQL (Variables/Parameters in Links OpenAPI-Specification#1327 (comment))
• schemathesis to perform automated property-based tests (https://schemathesis.readthedocs.io/en/stable/stateful.html)
• ..?

[handrews]

Also of interest (closed in the other repo as the discussion should continue here, please feel free to copy over any points of particular interest):

• Relationship properties OpenAPI-Specification#601
• Flexible Path/URI Structure Using Linking OpenAPI-Specification#783
• link object language OpenAPI-Specification#1011
• Link to operation mapping OpenAPI-Specification#1315
• Variables/Parameters in Links OpenAPI-Specification#1327
• Proposal for incorporating state transition into Open API OpenAPI-Specification#1329
• link object scope OpenAPI-Specification#1593
• Using Links to set a field in the target operation's request body OpenAPI-Specification#1594
• openapi link vs hypermedia link to represent relationships in APIs OpenAPI-Specification#2122
• Feature suggestion: "Backlinks" - Links defined the inverse of the way they are currently OpenAPI-Specification#2196
• Allow Links to Schema objects (Primitives/Objects/...) OpenAPI-Specification#3228