[
https://issues.apache.org/jira/browse/SOLR-16880?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17793858#comment-17793858
]
Jason Gerlowski commented on SOLR-16880:
----------------------------------------
bq. An alternative approach would be to check in the generated spec to our
source tree.
bq. I think it would do us well to keep [...] (openapi.json) in source control
[...] published openapi.json via GitHub files
(Tagging you two directly since I'm replying here so late, sorry I missed this
earlier [~dsmiley] [~mdrob])
We can go this route if there's consensus, but I'm still not quite sold.
One big difference between an OAS and something like version.lock is the
intended audience: version.lock is intended for developers (or for gradle
itself, really), while an OAS is for users. And as such, IMO the OAS would
benefit from some of the trappings that surround all our other user-facing
artifacts: hosted in the same place, signed and checksummed, etc.
Totally agree with you about how nice some of the "version control"-y benefits
are. But we already largely have those with Solr's new-ish 'api' submodule.
Changes to any files in that module _are_ changes to our v2 APIs. So PR
impact, etc. is already surfaced in the way you described - you just look for
the 'solr/api' subdir instead of the OAS path.
All-in-all, I'm not sure committing the OAS gets us much additional value. But
what do you guys think? Am I missing or overstating anything?
> Make OpenAPI spec a release artifact
> ------------------------------------
>
> Key: SOLR-16880
> URL: https://issues.apache.org/jira/browse/SOLR-16880
> Project: Solr
> Issue Type: Improvement
> Components: v2 API
> Reporter: Jason Gerlowski
> Priority: Major
>
> SOLR-16346 added OpenAPI spec generation to Solr - allowing us to produce a
> detailed description of our v2 APIs (or at least - those APIs implemented
> using JAX-RS).
> These spec files have a lot of potential uses - from generating
> documentation, to API clients, to web UIs. These have a lot of promise, but
> it will take the community time to implement and adopt some of them.
> We should make the OpenAPI spec available as a release artifact, so that
> users can more easily take advantage of it. Having it published on each
> release will also allow us to compare specs across versions, as a way to
> detect backcompat breaks before changes go out the door.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscr...@solr.apache.org
For additional commands, e-mail: issues-h...@solr.apache.org
