I did try to write a OpenAPI specification for V2, and discovered how much customization/specifics I would have to do, and gave up because we were so very different. With the “experimental” tag, we could evolve towards the OpenAPI spec standards if folks wanted to ;-)
> On Oct 29, 2021, at 11:48 AM, Timothy Potter <[email protected]> wrote: > > Does the v2 API support OpenAPI? I looked over the docs and it seems > like not, which is a shame. OpenAPI > (https://swagger.io/specification/) opens up a mature ecosystem of > tooling. The _introspection endpoint seems nice but if automated tools > can't understand it, then our users can't auto-generate SDKs or > interact with the API using tools like SwaggerUI, and so on. > Once your API is OpenAPI compliant, you don't need to "document" it, > tools will do that for you. > > I really think adopting this standard should be part of this > conversation, otherwise, we're just re-inventing the wheel around API > design and leaving too much heavy-lifting for ourselves. > > Tim > > On Thu, Oct 28, 2021 at 11:40 AM Jan Høydahl <[email protected]> wrote: >> >> +1 to experimental (java level). >> In user facing docs and tutorials, we can encourage use, with just a minor >> note somewhere that it may still change. >> When users report bugs there will always be a workaround — use v1 until next >> release.. >> >> Jan Høydahl >> >>> 27. okt. 2021 kl. 23:18 skrev David Smiley <[email protected]>: >>> >>> >>> I agree that *very* few users use V2. Ok I do at work but it's maybe one >>> API endpoint so whatever. We should free ourselves from the burdensome >>> constraints of back-compat until V2 is sufficiently ready, whenever that >>> is. So I agree with labeling it experimental and we can elaborate on that >>> is the upgrade notes. Some APIs I think are only V2, so we can clarify >>> that we're not saying the underlying functionality is experimental. Not >>> only do we have to concern ourselves with inconveniencing some users, we >>> have to face the reality of our limited dev resources, and thus not make >>> the prospect of improvements too hard (nor on potential contributors). >> >> --------------------------------------------------------------------- >> To unsubscribe, e-mail: [email protected] >> For additional commands, e-mail: [email protected] >> > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > _______________________ Eric Pugh | Founder & CEO | OpenSource Connections, LLC | 434.466.1467 | http://www.opensourceconnections.com <http://www.opensourceconnections.com/> | My Free/Busy <http://tinyurl.com/eric-cal> Co-Author: Apache Solr Enterprise Search Server, 3rd Ed <https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw> This e-mail and all contents, including attachments, is considered to be Company Confidential unless explicitly stated otherwise, regardless of whether attachments are marked as such.
