-
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
Reconsider multiple basePath values #562
Comments
parent issue #560 |
I think we should consider real life scenarios for this issue. https://www.googleapis.com/youtube/v3 Or different subdomain: https://api.dropboxapi.com/2 I think RAML have pretty good solution for this problem: And I think template parameters in |
Thanks @IvanGoncharov. Aside from ease of modeling, what do you think of three concerns I listed above? I don't think the hard part is how to model it, which RAML does, it's more about how you use it. |
My main point here is that separate baseUrl for file upload/download is common pattern and it has performance reasoning behind it. So it will not disappears in nearest future and should be dealt with as first-class citizen in OpenAPI world. Also it don't require any special mechanism to handle just template parameters for
I'm also not like idea of putting two different APIs in one spec.
I'm totally against putting separate APIs into one Swagger file it's creating a total mess. Moreover in my project I work with hundreds of different real-world APIs and I only had problems similar to the ones that I presented in my previous comment.
Can you provide more concrete example, because right now I don't see any problem? |
@IvanGoncharov API design choices aside, it's difficult to discount the number of times we've been asked for a solution for multiple basePath support since we published 2.0. We had plans on introducing a solution to it (still have it somewhere) as an external extension, but we abandoned it partly due to lack of resources and partly because there's an alternative solution such as apis.json. |
@webron I think we should distinguish two scenarios:
I agree that first should be solved by totally separate format. |
Here is my proposal for this: Add support for multiple hosts by adding optional attributes at the path and operation level. When not present, the top-level settings will apply: host: <host>
basePath: <basePath>
schemes:
- <scheme> Path-level example: paths:
/pet/upload:
host: https:/pets.com
basePath: /uploadMe
get:
operationId: theUsualStuff Operation-level example: paths:
/pet/upload:
host: https:/pets.com
basePath: /uploadMe
get:
host: https://pets.com
basePath: /uploadMe
operationId: theUsualStuff |
I think from an API description authoring perspective, this just muddies the waters. Not only can I do the same by putting the
There could be more permutations but I have no idea what multiple base paths or per path/operation level base paths should be handled. What was once a singular view of your API is no longer the case. I have to do some computation just to figure out what this API looks like and that violates the human readability of the OpenAPI documents. |
To me, when I have an API it is host/path agnostic. I write an API and whether I deploy it to QA, test, prod, ... my API looks and works the same. Now I realize based on the deployed environment that things like the hostname will obviously be different and that the base path could potentially be different but my API is still the same. The same operations will return the same objects and have the same contract. All of this being said, I often wonder why these details are even in the OpenAPI documents at all. |
This might not be the proper place for that last comment. |
@whitlockjc there are no path permutations to worry about. This is only for the execution of an operation, and it would follow the same inheritance as, say,
I don't think this is a modeling concern, more an operations concern. It allows a user to send a request to an alternate location which as @IvanGoncharov mentioned, can make sense. |
I got you. That makes more sense now. Thanks for clarifying. To me, this seems like a feature where you want to have a single OpenAPI document to sit in front of N different real APIs. Is this a use case we want to support? For the APIs that share a common host name, to me that is a single API and you can easily support this with |
@whitlockjc I get it--one could take this very far in the direction of having many hosts in one specification, we can't keep people from abusing the idea. But I do think it's worth supporting this construct. Tooling will be easy to handle it. |
creating separate spec document with code duplication if you have more than one subdomain is so stupid |
Try to keep it cool, @november1306 |
This was one of those features that shipped with swagger 1.0, 1.1, and 1.2 but was removed in 2.0.
The current spec does not allow multiple hosts to be defined for execution. You can host the spec in different pieces and across multiple hosts, but the execution shall be for a single host. That host is configurable in the spec, but it applies to all operations.
There has been pushback on this from a number of people so I'd like to put it back out in the open. We can reintroduce a construct for multiple hosts. Having gone through the pains of both implementing and supporting it in tools, I would strongly suggest we do not.
My reasoning:
http
operation from ahttps
-hosted page, for example) introduces show-stopping compatibility issues for web-based tools. Multiple hosts in a single spec will exacerbate this issueSo this ticket gives some background and a recommendation for the next version. If there is strong objection, now is the time.
The text was updated successfully, but these errors were encountered: