-
Notifications
You must be signed in to change notification settings - Fork 61
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
[FEATURE] Keep the OpenAPI specification vendor-neutral / vendor-agnostic #522
Comments
When I introduced this feature in #510 I did not intend it to be biased towards supporting AWS in any way, but I did want to run the tests against Amazon Managed so I annotated some APIs. As is, the spec welcomes other keywords, be it From the mechanics POV, what you are looking at is the source for the spec, not the spec. We currently publish the all-versions spec in a release that includes these Given the above, what's a better place to put the information that a particular distribution of OpenSearch supports or doesn't support an API or an API parameter? |
I think it is an option but not sustainable way to manage that for many reasons:
This is 100% cloud vendor decision: dev portal, Github,web site, ... (anywhere literally). What we could help with - tooling for easy reconciliation. |
I suppose I wouldn't be against it! As a positive, this gives incentive to cloud vendors not to deviate from spec and gives the community tooling to check that a vendor complies with the spec. |
To be a bit more specific/pedantic, I think it's less a "complies with the spec" as "allows a spec API". I happened on this issue following a link trail with a completely unrelated issue, but it's very relevant. Specifically, the spec includes core and multiple different plugin APIs. Any given provider may choose to remove some plugins, or possibly remove access to a subset of the APIs. The "cloud vendor" certainly needs a way to annotate the spec with a "we do this"/"we don't do this" at various levels of detail (the entire API, or a limitation on which enum values of a parameter are legal, etc.). What makes this more than a "cloud vendor" problem is the fact that front-ends / apps need to know what is supported. It's a poor app user / customer experience to have a menu where you can select an option that the API is spec'd to support, and it fails. TLDR: We need a way for an app/front-end to query the spec (filtered by <insert cloud vendor here>) to know whether to display options on it's UI. I don't know if that's part of this spec or part of some companion filtering program, but it's an obvious need. |
I believe it is out of scope for us to consider the custom deployment / tailoring / forking / etc: as a project, we provide single unified distribution (core / plugin / extension specs), what consumers could do with it - it is their choice.
The service (filtered by |
This project contains OpenApiVersionExtractor that can generate a spec for a given version and distribution of OpenSearch using these annotations. The services should make the output of that available under https://service/openapi-spec.yaml or something like that. The merger tool needs a command line switch to take in the distribution like it takes in the version already (please contribute?). We can move these annotations from the spec into some yaml that doesn't have to live in this repo (eventually), which I think would satisfy all the concerns above. Do note though that the spec is changing fast right now given that it's ~50% complete, I'd prefer not to do it right away. |
Getting rid of |
A possible solution would likely be a fork of this repo customized (by the provider) and kept up to date with merges/cherry-picks. As long as the feature is available to use it should help satisfy the need. |
Is your feature request related to a problem?
Coming from opensearch-project/opensearch-java#1152 (comment) and #510, I understand the bias towards supporting AWS, but I honestly believe the spec has to be vendor neutral / agnostic.
What solution would you like?
I believe it should not "pollute" the spec with
x-distributions-excluded:
. It should be feasible to keep the distribution specific details outside of the spec and allow the distribution specific spec to be produced if needed:For example:
openapi-oss.yaml
openapi-aws.yaml
(would only contain new APIs, excluded APIs or APIs that are tailored)The final spec for AWS:
openapi-oss.yaml
+openapi-aws.yaml
What alternatives have you considered?
Keep asking vendors to add their own distribution perferences
Do you have any additional context?
N/A
The text was updated successfully, but these errors were encountered: