search

PhilanthropyDataCommons / sdk

Instructions and supporting files for SDK generation
GNU Affero General Public License v3.0
1 stars 0 forks source link

Migrate to OpenAPI Generator #26

Closed slifty closed 4 months ago

slifty commented 6 months ago

This PR moves the sdk tools to use OpenAPI Generator instead of Swagger Codegen. OpenAPI Generator is a community fork, and is much more actively maintained. This move will allow future SDK builds to benefit from some bug fixes in the spec mapping to types, as well as support version 3.1 in future (see https://github.com/PhilanthropyDataCommons/service/pull/854)

Resolves #25

You should be able to test this by following the README to generate the SDK -- check out the PlatformDataProviderResponse type and notice how data is an object rather than any 🎉

reefdog commented 6 months ago

@slifty My review above was actually written under a bit of pressure to finish my day, and I understated how useful this will be. I'm really excited about it! Also, the bit about it being a breaking change wasn't meant to be dismissive -- I think it's perfectly fine that the front end will need to change to adapt to this. I was just noting it so you could decide if that changed the rollout/versioning strategy. (We're pre-1.0 so I assume not, just FYI though.)

slifty commented 6 months ago

Ooooooo really appreciate the deep dive -- our lack of test suite for this makes changes to the sdk much more fraught.

I did NOT realize all those fixes -- the total is truly a fix (that was always being provided by the backend, just not included as part of the sdk type). The date "string" is actually a surprise to me but I think it's... correct? The thing being returned is a string, not a date object, so it comes down to what your fetch middleware does... Does it convert the string to a date for you? If so, then we should figure something out.

I'll ping you offline to see if we can maybe briefly pair on this, or alternatively I'll try to figure it out and circle back here.

That last thing I'd like to avoid, since CreatedBy is used in a few places and they shouldn't be distinct. I'll try to figure out what's up. It's very likely that the change is NOT going to be in this PR / repo, but rather fixes to the openAPI spec. The good (well, circumstantially good) news is that the SDK doesn't get re-built with changes to this repo, so we can fix this tooling, include a version bump in the template, and then the sdk version will be updated accordingly.

slifty commented 4 months ago

This may be famous last words, but re-reading the above it looks like everything is all set at this point, and the next step is to update the openAPI spec. That may culminate in the need for more changes here, but we'll cross that bridge if we get there.