-
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
Allow for overloading/aliasing of route path #213
Comments
I think that my change in #440 would also address this use case. |
Nice! Looks like it. |
Looking back at the question and the reply (SO), there's potentially a way to do that with 2.0 but it may not be a convenient way in some cases. Let's revisit this. Parent: #560. |
Propose rejecting this per #639 |
Not clear how setting allowed languages would solve the problem of internationalized spellings for routes? If you can elaborate, that'd be great. |
It's not, but this feels a bit of a niche case that doesn't warrant special treatment. Since Path Item Object can be referenced, it should suffice for this case. Voting to reject explicit support for this. |
If we reject building in something for this, could we at least document the workaround here (with an example YAML)? |
I've also wanted a solution for this, not so much for internationalized variants, but for normal API evolution. For example, a path is called Note that a simple |
Agreed David, I wonder if this belongs in a new thread as a proper feature request? |
@grapefruit since this is already tagged at "OpenAPI.Next Proposal" and remains Open, this ticket should suffice. If think adding another won't help. |
[Update: obsolete, I had just some different error in my .yaml ] |
|
There must have been a different error in my .yaml, now it works like expected! Thanks very much for the very fast response andI wish all the programmers a happy new year! |
I'm researching migrating our existing API to OpenAPI, and this would be a killer feature to help with migration. |
Also looking for this feature! |
I think you would have to redefine the original X like this: /original-x:
description: Redirects to the new X
get:
responses:
'308':
description: This resource has been moved
headers:
Location:
schema:
type: string
default: /new-x |
@mattbishop The problem with this approach is that it is hard in automatic fashion to know what is content schema to expect in the response after the redirect. There should be some way to be able to say that |
The content schema of /new-x isn't a concern of /original-x. This is the same behavior as HTTP now. The client will follow Location to /new-x and negotiate the content-type there. |
But codegenerators do not behave like that, at least not that one I have tried. When I try to generate code for So there should be more concrete way to say where is the redirect going, to which API endpoint (and not that just to some URI). |
@mitar has a great point and maybe that's what the $ref idea earlier can solve for us. |
I opened #2512 for better handling of redirects (which can be a different thing than aliasing). |
Just jumping back in here – I agree that an alias path is not the same thing as a redirect. A redirect implies the resource was originally there, and is now moved. Instead, we want a true alias, where both paths return the same value. This is important for cases where one location might naturally spell a word differently than another, for example UK/Canada vs. US 'flavours' vs. 'flavors', or 'catalogue' vs. 'catalog' . I'm not attached to one solution or the other, but I'll admit that the
|
wondering if this feature was added. i have a controller with 2 paths as below, But i want only "/user/vehicle" to be included in open api doc. |
I'm exactly in that situation right now. A feature request on an API that I'm working on requires me to rename a path. But for the documentation part of this (that I do using Open API), I don't see any other solution rather than copy pasting the definition I've for the old path to create the new path. Ideally, I'd want, in my Open API JSON file, to rename my old path into the new path, and then create a new entry with the old path and make it refer as being an alias to the new path. But yeah, looks like I can't do that :'( |
OpenAPI 3.1 allows defining reusable path item objects so one can define the full operation(s) in as reusable path items in paths:
/route/a:
$ref: '#/components/paths/my-reusable-ops'
/route/b:
$ref: '#/components/paths/my-reusable-ops'
components:
pathItems:
my-reusable-ops:
get:
parameters: ....
responses: ....
put:
parameters: ....
requestBody: ....
responses: .... This is almost a solution for the narrower "exact alias" case - both paths will have identical operations, no copy/paste. However, it falls short in at least two regards:
A path item may also be a paths:
/route/a:
put:
summary: Update an A thing (deprecated)
description: Perform a full replacement of the representation of an A thing.
Instead of this path, use the `put` operation on `/route/b`.
$ref: '#/components/paths/my-reusable-ops/put'
get:
summary: Fetch an A thing (deprecated)
description: Return the representation of an A thing.
Instead of this path, use the `get` operation on `/route/b`.
$ref: '#/components/paths/my-reusable-ops/get'
/route/b:
put:
summary: Update a B thing
description: Perform a full replacement of the representation of a B thing.
This replaces the `put` operation on `/route/a`.
$ref: '#/components/paths/my-reusable-ops/put'
get:
summary: Fetch a B thing
description: Return the representation of a B thing.
This replaces the `get` operation on `/route/a`.
$ref: '#/components/paths/my-reusable-ops/get' However, you still cannot add an paths:
/route/a:
put:
summary: Update an A thing
description: Perform a full replacement of the representation of an A thing.
Instead of this path, use the `put` operation on `/route/b`.
$ref: '#/components/paths/my-reusable-ops/put'
operationId: updateAThing
deprecated: true
get:
summary: Fetch an A thing
description: Return the representation of an A thing.
Instead of this path, use the `get` operation on `/route/b`.
$ref: '#/components/paths/my-reusable-ops/get'
operationId: getAThing
deprecated: true but reference objects cannot have such additional properties. |
@DavidBiesack Thanks for the detailed answer ! |
So in recent JSON Schema (after 7, starting with draft-2019-09) they redefined |
@mitar OAS 3.1 already allows a |
Awesome. Then your comment:
Does not hold anymore? So we could do the "ideal" approach you described? |
OAS allows |
OK, so my statement then still holds, should we move OAS to be closer to JSON Schema and be without a restriction on properties which can be next to |
The way So, moving closer to parity with JSON Schema shouldn't be a goal, but that doesn't mean removing restriction on which properties can be next to |
@brandonscript |
got it, escape characters |
Per this question: http://stackoverflow.com/questions/27004847/provide-alternate-international-spelling-for-defined-swagger-route/27013027#27013027
It would be great to allow aliasing of route paths for such uses as international spellings of words
The text was updated successfully, but these errors were encountered: