Move to using OpenAPI spec with generated code?

[robrbecker]

So, I've had this idea brewing for some time and I thought I'd throw it out there to get people's thoughts on it.

There's a long list of improvements to this project that could be done. A big one is better automated testing and how to keep that up to date and accurate with what github actually responds with. Turns out this is already something that github does with client libraries in other languages. They are called Octokits https://github.com/octokit and are available in a handful of official supported languages. These are all based on the the open api specs defined here https://github.com/octokit/openapi

There are code generators that take openapi specs and generate client code, including Dart here https://github.com/OpenAPITools/openapi-generator

Using this approach would mean:

• Always up to date with the Github API
• 100% of the github API would be provided
• Always accurate with fields & data (no more missing fields on classes, typos in json key names)
• Testing is generated as well
• Can use the provided github fixtures (https://github.com/octokit/fixtures) with a fixture server (https://github.com/octokit/fixtures-server) to test the full API works as expected.

Those are all huge benefits in my mind. The obvious downside is that it is basically an entirely new codebase and would 100% break all users of this library. So my questions are:

• Would you be interested in the new approach?
• Would you prefer if the new approach was an entirely new library or a breaking change release of this library?
• Are there any other concerns or downsides that I should be aware of?

All feedback is welcome!

pinging => @pq @kendfinger @kevmoo @Pacane @axel-op

[kevmoo]

A breaking change release of the current library is ideal, IMHO. I don't think anyone would want to maintain the legacy. If you're game to go down that path, I support it!

…

On Mon, Feb 22, 2021 at 3:18 PM Rob Becker ***@***.***> wrote: So, I've had this idea brewing for some time and I thought I'd throw it out there to get people's thoughts on it. There's a long list of improvements to this project that could be done. A big one is better automated testing and how to keep that up to date and accurate with what github actually responds with. Turns out this is already something that github does with client libraries in other languages. They are called Octokits https://github.com/octokit and are available in a handful of official supported languages. These are all based on the the open api specs defined here https://github.com/octokit/openapi There are code generators that take openapi specs and generate client code, including Dart here https://github.com/OpenAPITools/openapi-generator Using this approach would mean: - Always up to date with the Github API - 100% of the github API would be provided - Always accurate with fields & data (no more missing fields on classes, typos in json key names) - Testing is generated as well - Can use the provided github fixtures ( https://github.com/octokit/fixtures) with a fixture server ( https://github.com/octokit/fixtures-server) to test the full API works as expected. Those are all huge benefits in my mind. The obvious downside is that it is basically an entirely new codebase and would 100% break all users of this library. So my questions are: - Would you be interested in the new approach? - Would you prefer if the new approach was an entirely new library or a breaking change release of this library? - Are there any other concerns or downsides that I should be aware of? All feedback is welcome! pinging => @pq <https://github.com/pq> @kendfinger <https://github.com/kendfinger> @kevmoo <https://github.com/kevmoo> @Pacane <https://github.com/Pacane> @axel-op <https://github.com/axel-op> — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#245>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAEFCT6RKOE54CSGMU6EP3TALQ5HANCNFSM4YBNPFKQ> .

[pq]

I'm with @kevmoo. Sounds like this is the best path forward for all of us and well worth a little pain in migration. I say go for it!

[yahu1031]

A Good documentation is needed to this awesome package. 🙏🏻

[robrbecker]

I agree better documentation is needed. Moving to the OpenAPI generated code would mean that documentation for each method and service comes from the source (github).

[kuhnroyal]

The dart-dio generator is probably not yet generating all the correct inline docs, but this should be an easy improvement.

[robrbecker]

Hmm looks like there a decent bit of work needed to properly support dart still, and then add null safety on top of that OpenAPITools/openapi-generator#8179
OpenAPITools/openapi-generator#7850

[kuhnroyal]

You could try the dart-dio generator. It uses the dio library and built_value. It supports more features than the normal dart generator which is currently stuck with some problems in de/serialization, although there is some progress there as well.
If you can create a repro, we might be able to fix the issues step by step.

[robrbecker]

What's the path forward? Implement more for Dart? Push for github to change their spec? Add the ability to the dart generators to provide workarounds for the problem areas?

[kuhnroyal]

There are a couple problems and I didn't check the spec out yet, only generated from your branch.

1. Minor escape problems for String enums named like Won't fix
2. Some problems around serializing null with built_value, this is being worked on
3. A ****load of inline objects are used in this spec - the generator generates them as inline_objectxxx/InlineObjectXXX. This is not very useful, need to find a naming mechanism.
4. Inheritance is not implemented in any of the Dart generators

All these problems are solvable but this takes time. The inheritance implementation will be added at some point but right now it is not my focus.
I suggest generating with a couple different generators (Java, Kotlin, etc.) and see if some of them generate this in a better way. Then we can use them as guidance. Not all generators behave the same way.

If you want to address some of these things, be my guest, I will happily review.

[robrbecker]

1 & 2 sound fixable.
3) I noticed all the inline objects and yeah that's gross. I was hoping the generator could turn those into optional named parameters?
4) Inheritance support. yikes. That sounds like a big effort.

[robrbecker]

Looks like it could be possible with built_value using mixins and implements ?https://github.com/google/built_value.dart/blob/master/example/lib/polymorphism.dart

[kuhnroyal]

Yes, I have experimented with this a while back and hit some roadblocks around default values if I remember correctly. But this should be possible.

Regarding the inline objects, those are mostly response objects, look in the spec for the meta/root operation. The response is inline and has no name anywhere, this is what causes the inline objects, and I am not sure what to do about it, could probably implement some custom naming based on the operation but thats all guessing.