Yes that's true, if you only want to generate clients and not the server then you can definitely have an easier time of things.
On Tue, 9 Aug 2022 at 14:21, Jason Gerlowski <[email protected]> wrote: > Thanks for the insight Colvin! Spec-driving-the-code sounds appealing > in a lot of ways (I'd love to have defaults handled uniformly across > Solr, for instance), but I think Jan's right that it's probably > infeasible for Solr. > > And "point taken" about expecting some issues with the tooling! > > Best, > > Jason > > On Tue, Aug 9, 2022 at 6:10 AM Jan Høydahl <[email protected]> wrote: > > > > I have recent experience from a SpringBoot / Kotlin application where we > use code-first annotation driven OpenAPI definition. I think that will be > the only feasible way for Solr. > > > > The sweet thing about that approach is that the OpenAPI definitions and > documentation is all done inline with the code using @Tag and @Operaton > annotations, and there is no drift. You can then generate the OpenAPI spec > JSON from code to do (client) code generation. Swagger UI comes for free in > the app itself with a simple dependency. > > > > Jan > > > > > 9. aug. 2022 kl. 11:45 skrev Colvin Cowie <[email protected] > >: > > > > > > I spent the first few months of this year adopting OpenAPI 3 spec in > our > > > product, which has a fairly large API. > > > > > > We previously generated a Swagger 1.0 spec from our Java code, now > we're > > > generating our POJOs and JAX-RS endpoints from the OA3 spec. > > > > > > Aside from needing to get off outdated Swagger 1 tools, we were > motivated > > > to go spec-first to close the gap between our API designs "on paper" > and > > > the actual implementation, be more rigorous with our API definitions, > and > > > to (hopefully) speed up / simplify development in the future. > > > > > > Migration for us was complicated by the fact that our existing > codebase was > > > inconsistent when it came to things like default initialization of > fields > > > in POJOs, use of primitives/Objects, and List vs Collection etc. While > the > > > code generator is consistent in what it produces (naturally). Our > codebase > > > is also fairly tightly coupled between transport classes and model > classes > > > as we eschewed the use of models for a lot of it. We did modify the > > > templates and add extra x- vendor attributes to our spec to control the > > > generation of certain things where we needed to though, so we were > able to > > > maintain some of our existing idiosyncrasies when necessary. > > > > > > We were also bitten by some bugs/inconsistencies in the OA3 tooling we > used > > > - even though OA3 is a specification, everyone seems to have a slightly > > > different interpretation or level of support for some parts of it. > > > The main pain point for us is around support for polymorphic types / > > > inheritance ( > > > > https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/), > > > where modelling them one way works for one viewer but not another, or > > > doesn't work for code generators, or api-diffing and so on. > > > > > > We use > > > > > > - https://www.apicur.io/apicurito to edit the spec > > > - https://github.com/OpenAPITools/openapi-generator to generate > Java code > > > - https://github.com/rapi-doc/RapiDoc as our viewer, we like > > > https://redocly.com/redoc too > > > - https://github.com/OpenAPITools/openapi-diff to check for > (breaking) > > > changes > > > > > > Getting to where we are was quite painful - it would definitely be a > lot > > > easier to adopt a spec-first approach in a brand new project - but now > that > > > we're here it was probably worth it for the consistency and API-first > view > > > it brings. > > > > > > So I hope I don't put you off trying it, but just be aware that some > things > > > won't work as well as you might expect them to and you might find > yourself > > > contributing to some of these OpenAPI projects to get things to work > the > > > way you need them to :) > > > > > > Colvin > > > > > > > > > On Tue, 9 Aug 2022 at 08:30, Jan Høydahl <[email protected]> > wrote: > > > > > >> Makes sense to explore at this point to figure out best order of > > >> development. And with the door open to slightly adapt some URL > patterns in > > >> v2, should it be required, it's less likely that roadblocks would > derail > > >> the entire effort. > > >> > > >> Jan > > >> > > >>> 8. aug. 2022 kl. 18:10 skrev Jason Gerlowski <[email protected] > >: > > >>> > > >>> Hey all, > > >>> > > >>> I spent some time last week digging into OpenAPI and spiking out how > > >>> it could be integrated into Solr. I came away very impressed. It > > >>> opens a lot of really cool doors: auto-generated clients and docs, > > >>> "Swagger UI", backcompat/api-breakage detection, etc. There's a LOT > > >>> to gain. > > >>> > > >>> Another takeaway from my spike though was that OpenAPI is much more > > >>> "do-able" in JAX-RS projects. It's possible to create > > >>> annotation-drive OpenAPI specs without JAX-RS, but it requires more > > >>> explicit (and duplicative) documentation of each API's inputs and > > >>> ouputs, which probably isn't maintainable in a project as large as > > >>> ours. > > >>> > > >>> With that in mind, I'm planning on returning to the JAX-RS spike Eric > > >>> and I did months back, and updating it to cover some of the issues > > >>> this thread brought to light. In particular: security integration > and > > >>> serving collection/core-specific APIs. If that pans out, we can > > >>> figure out next steps from there. (A SIP? A JIRA?) > > >>> > > >>> Before I start that effort though, I figured it'd be worth > > >>> double-checking that there are no -1's/vetos on the idea > sight-unseen? > > >>> If so, let me know! > > >>> > > >>> Best, > > >>> > > >>> Jason > > >>> > > >>> > > >>> On Fri, Jan 7, 2022 at 5:36 PM Eric Pugh > > >>> <[email protected]> wrote: > > >>>> > > >>>> I wanted to share that our hack day did happen, but it went a bit > > >> sideways as we spent the first half of the day experimenting with how > to > > >> support CORS in Solr. So API related, but not JAX-RS API specific. > The > > >> second half of the day got consumed by $dayjob. > > >>>> > > >>>> We’re going to pick it up again next month, and dig into trying out > how > > >> existing Solr security would work. > > >>>> > > >>>> https://github.com/gerlowskija/solr/tree/cors_stuff if you want to > see. > > >>>> > > >>>> Eric > > >>>> > > >>>> > > >>>> On Dec 9, 2021, at 10:06 AM, Eric Pugh < > [email protected]> > > >> wrote: > > >>>> > > >>>> Thank everyone for the input, it’s been a productive conversation! > > >>>> > > >>>> Jason and I are planning on another hack day Jan 7th to take some of > > >> the feedback, and work more on how our spike can help meet some > > >> concerns/show promise, so we’ll report back then! > > >>>> > > >>>> We’re planning on zooming during US East Coast hours, and I’ll drop > the > > >> Zoom invite in the ASF Slack for anyone who wants to join in and say > hi! > > >>>> > > >>>> Eric > > >>>> > > >>>> > > >>>> > > >>>> On Dec 7, 2021, at 3:47 PM, Mark Miller <[email protected]> > wrote: > > >>>> > > >>>> Two cents from the peanut gallery: > > >>>> > > >>>> I’ve looked at this before. My opinion: > > >>>> > > >>>> Our stuff was a just terrible, take your pick on the api version. > > >> Reasons are numerous. > > >>>> > > >>>> Custom end points is an anti feature. Even worse for cloud. > > >>>> > > >>>> JAX-RS looked ridiculously sensible. > > >>>> > > >>>> > > >>>> -- > > >>>> - MRM > > >>>> > > >>>> > > >>>> _______________________ > > >>>> Eric Pugh | Founder & CEO | OpenSource Connections, LLC | > 434.466.1467 > > >> | http://www.opensourceconnections.com | My Free/Busy > > >>>> Co-Author: Apache Solr Enterprise Search Server, 3rd Ed > > >>>> 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. > > >>>> > > >>>> > > >>>> _______________________ > > >>>> Eric Pugh | Founder & CEO | OpenSource Connections, LLC | > 434.466.1467 > > >> | http://www.opensourceconnections.com | My Free/Busy > > >>>> Co-Author: Apache Solr Enterprise Search Server, 3rd Ed > > >>>> 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. > > >>>> > > >>> > > >>> --------------------------------------------------------------------- > > >>> 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] > > >> > > >> > > > > > > --------------------------------------------------------------------- > > 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] > >
