-
Notifications
You must be signed in to change notification settings - Fork 9.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Links proposal (updated) #742
Conversation
To support operation linking, as suggested in #688, I propose the following:
Additional considerations:
Spec changes
|
missingValue: null | ||
``` | ||
|
||
In situations where variables appear in an array, an array of variables will be extracted. For example: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This needs more documentation
operationId| string | the name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`. This field is mutually exclusive with the `href` field. Relative `href` values _may_ be used to locate an existing Operation Object in the OAS. | ||
parameters | Link Parameters Object | an Object representing parameters to pass to an operation as specified with `operationId` or identified via `href`. | ||
description | string | a description of the link, supports GFM. | ||
^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@ralfhandl I added description
and x-*
extensions
href | url | a relative or absolute URL to a linked resource. This field is mutually exclusive with the `operationId` field. | ||
operationId | string | the name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`. This field is mutually exclusive with the `href` field. Relative `href` values _may_ be used to locate an existing Operation Object in the OAS. | ||
parameters | Link Parameters Object | an Object representing parameters to pass to an operation as specified with `operationId` or identified via `href`. | ||
headers | Link Headers Object | an Object representing headers to pass to the linked resource. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@DavidBiesack With the addition of headers for the linked resource, we can traverse media types now.
approved by @OAI/tdc |
I was approaching this PR with some hope that it could be used to support hypermedia types being represented in OAS, but I see now that there's a requirement for the links to be "static." This requirement alone breaks the coupling semantics for Web Linking, on which (nearly?) all the hypermedia types depend. And that's okay if that's not the supported use case for this feature. But it leaves me a bit bewildered. Can someone help by defining use cases or existing APIs that could benefit from this feature in its current form? It seems like this introduces a lot of hopping around between references to grok what's going on. What are the intended benefits? Maybe it's obvious to most people. Hopefully, it is. But right now, I'm in the dark. Thanks. |
@kevinswiber consider reading the comments in the previous (mangled) PR and the corresponding issues for the rationale |
The previous PR was updated, and the comments got all jacked up. So here's a new PR, the old one has been closed but you can see comments there in all their glory.