deprecate openapi v2 for v3 - Githubissues

airr-community / airr-standards

AIRR Community Data Standards

https://docs.airr-community.org

Creative Commons Attribution 4.0 International

35 stars 23 forks source link

deprecate openapi v2 for v3 #739

Open schristley opened 6 months ago

schristley commented 6 months ago

[ ] Currently, the PR check converts the v2 schema into v3 then compares with jsondiff. Swap this so v2 is generated from the v3 schema.
[ ] write simple shell script that converts the v3 schema file to v2 and copies the schema to the language subdirectories
[ ] switching to #688 should be straight forward, it was for javascript
[ ] review I/o routines
[ ] This leaves R. Need to change references of x-airr: nullable to nullable:

schristley commented 6 months ago

@javh I can do the first 3 items if you feel the R changes are doable. There might even be a validation library available now?

bcorrie commented 4 months ago

@javh @schristley does this seem feasible for v2.0?

schristley commented 4 months ago

Trying to completely move to Open API v3 will be too much for the V2 release, but we can do it in increments. At a minimum, we want to release the OpenAPI v3 spec alongside the v2 spec, even if the language reference libraries aren't using them yet.

schristley commented 4 months ago

putting the initial moves that can go into V2 into PR #758

javh commented 4 months ago

Yep. I can handle R. I think it would be very good to swap over to OpenAPI V3 for AIRR v2, at least as the default used by the libraries. I don't think we necessarily need to deprecate V2 support if we have the converter.

schristley commented 4 months ago

Yep. I can handle R. I think it would be very good to swap over to OpenAPI V3 for AIRR v2, at least as the default used by the libraries. I don't think we necessarily need to deprecate V2 support if we have the converter.

@javh Ok, great, yeah I think we can get it done in time. The converter may be an issue though, it may be valid but it likely will be "ugly", will lose all comments, might have things out of order, etc. Do we care enough to hand-craft some code? Or we don't care anymore because it's auto-generated and won't ever be hand modified?

javh commented 4 months ago

We may not care. It's also not that big of a deal to manually maintain the V2 and V3 spec files if we need to, considering that we intended to be feature complete for the next release (AIRR v2.0).

schristley commented 4 months ago

considering that we intended to be feature complete for the next release (AIRR v2.0).

I love your wishful thinking! :-D

schristley commented 4 months ago

We may not care. It's also not that big of a deal to manually maintain the V2 and V3 spec files if we need to, considering that we intended to be feature complete for the next release (AIRR v2.0).

I was trying to think if doing the converter was worth it right now, because I think it would create a lot of churn in our PRs. Maybe a good compromise as you suggest is to manually maintain both through the v2.0 release, then switch on the auto-generation of V2. Then again, after v2.0 release, maybe just delete V2 and problem is resolved ;-D

schristley commented 4 months ago

Then again, after v2.0 release, maybe just delete V2 and problem is resolved ;-D

However, I'll note if we do that, then we also effectively deprecate the V2 of the ADC API #765 , not that I'm opposed to that either.