[PROPOSAL] Add a workflow that publishes this spec in OpenAPI format

[dblock]

What are you proposing?

Add a workflow that publishes a versioned output for this spec in OpenAPI format.

How did you come up with this proposal?

Coming from opensearch-project/OpenSearch#3090 (comment).

Why should it be built? Any reason not to?

We want to use existing tools that require OpenAPI.

What will it take to execute?

TBD

What are remaining open questions?

I propose this repo publishes the Smithy-format spec, along with OpenAPI spec at the same time as a "build". Would probably want the build infrastructure first.

[rursprung]

how do you plan on publishing it? as you know i'm a big fan of publishing such things to maven and i'd suggest to do the same thing here - then any consumer (incl. other opensearch projects) can just pull it in as a dependency and let maven/gradle deal with the details of where to find it. we use exactly this approach (OpenAPI specs published to maven & consumed from there) and it works fine for us.

[dblock]

@rursprung An API spec in maven assumes that everyone lives in a Java world and that the tooling to publish is Java - I wouldn't be so sure that's best, and I'd like to consume the API outside of that world, say to generate a Ruby client. So should we really be tying publication to maven?

[rursprung]

@dblock: we usually wrap all builds in gradle builds (e.g. also our npm builds are orchestrated through a small gradle wrapper) to take care of such things. but even where this isn't the case: if it's on maven it's accessible via HTTP and the URL is generally a stable pattern - so non-java builds can also access it and consume it. because the only thing which is generally accessible and tooling-agonstic is HTTP, and you get this out of the box with maven.

[dblock]

@rursprung You can see how me, a Ruby developer, would actually want it to be on Rubygems, or me, a node.js developer would want that to be on npm, by the same argument. I imagine you'd not want me to publish this spec to Rubygems and then tell you, a maven consumer, that it's "generally accessible and tooling-agonstic is HTTP"?

[rursprung]

@dblock well, i'm obviously a bit biased based on our internal tooling :)
one reasoning however is that the projects which implement these APIs (opensearch & opensearch plugins) generally are java projects and thus are using maven dependencies. how many non-java projects does opensearch have which implement APIs?
yes, for the consumers it looks different - but whether you publish it to maven and offer them an HTTP link or you publish it to and offer them an HTTP link to that is fully transparent to them.

i think the big difference to rubygems (i'm not familiar with that) and npm (i'm not familiar with this as i am with maven) is that with maven you can publish anything, with the others you're expected to publish code (a ruby gem can't just be a random yaml file, it's a ruby library, right? same for npm: it must be a JS/TS library). however, if it's possible to publish the openapi spec directly as such there, then why not - you can do that in addition to publishing it to maven.

and most consumers outside of the opensearch project should rely on the client library for their language and not on the openapi spec - that would only come into play if someone wants to use opensearch in a language where there's no client (yet) or has some other good reason to work without the library? and if they use the libraries they'll get them through the channel appropriate for their language (maven for java, ruby gems for ruby, npm for JS/TS, etc.) and won't ever bother with the openapi spec.

[VachaShah]

OpenAPI specs for OpenSearch are now published at https://opensearch-project.github.io/opensearch-api-specification/. Further improvements for specs are being tracked in #93.