Move to using OpenAPI spec with generated code? #245
Replies: 4 comments 13 replies
-
|
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>
.
|
Beta Was this translation helpful? Give feedback.
-
|
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! |
Beta Was this translation helpful? Give feedback.
-
|
A Good documentation is needed to this awesome package. 🙏🏻 |
Beta Was this translation helpful? Give feedback.
-
|
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). |
Beta Was this translation helpful? Give feedback.
-
|
The dart-dio generator is probably not yet generating all the correct inline docs, but this should be an easy improvement. |
Beta Was this translation helpful? Give feedback.
-
|
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 |
Beta Was this translation helpful? Give feedback.
-
|
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. |
Beta Was this translation helpful? Give feedback.
-
|
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? |
Beta Was this translation helpful? Give feedback.
-
|
There are a couple problems and I didn't check the spec out yet, only generated from your branch.
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. If you want to address some of these things, be my guest, I will happily review. |
Beta Was this translation helpful? Give feedback.
-
|
1 & 2 sound fixable. |
Beta Was this translation helpful? Give feedback.
-
|
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 |
Beta Was this translation helpful? Give feedback.
-
|
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 |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
-
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:
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:
All feedback is welcome!
pinging => @pq @kendfinger @kevmoo @Pacane @axel-op
Beta Was this translation helpful? Give feedback.
All reactions