-
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 issues #1039
Comments
1+ on clarifying that this refers to an operation. However, the example is unclear to me. In
is Instead, what about
or some JSON path query that picks an operation by id)
(I'm guessing at the right JSON path expression here; I'm not fluent in JSON path) |
I believe I'd rather not introduce another JSON querying mechanism. JSON Path doesn't have a formal spec as far as I know and it is overkill for most of our needs. |
I agree we don't want to adopt JSON Pointer, but I would like to be able to access operations by |
@DavidBiesack I think you meant to say "JSON Path". We already do support "JSON Pointer". I agree that using OperationId should be an option. Having a private identifier that has no reason to change is very useful. Tony's proposal is to have operationId and operationRef. Once we nail down exactly how operationRef will work, that should satisfy all requirements. |
Sorry for the lag responding. There is definitely some room for issues in here. The goal is to represent a locator to an operation ID inside an OAS doc--with that said, I think it makes sense to restrict the reference to live "in a valid OpenAPI Specification document" so the context of path and http method can be detected. I will modify the PR to take this into account. |
|
After a few deep dives into links, I've found--and others have pointed out many times--that there are some issues in the documentation of links.
href
field is not documented as intended. It was not supposed to point to a target resource--rather to the location to an operation definitionI suggest that we rename
href
to something more clear to ensure it's not confused with the target href. We clarify the purpose as a way to link to the operation instead. The reason is that becauseoperationId
is optional, it may be necessary to provide a JSON reference to locate an operation. For example:http:https://gigantic-server.net/foo/bar/operations#/superDuperOperation
This will be especially (or almost solely) useful when we talk about remote definitions of operations.
I also suggest that we revisit the target server locator. We can add a
server
field which holds a single Server Object which we can use the same templating mechanism for. Thus we can use request or response information to define target hosts.When we brought up the target server computation previously, we hadn't developed the templating mechanism. Now that it's baked (thanks @darrelmiller !) we should use it here.
The text was updated successfully, but these errors were encountered: