[Question] Do people successfully use this? #7490
Comments
|
As an anecdote, I can say that the Cloud Management team at Snow Software uses OpenAPI specs in production and has been for a couple years. We have one spec that's ~21k lines, another that's ~2k lines, and we are moving forward with more. That said, in total we use ~4 or 5 versions between the Swagger generator and the OpenAPITools generator because almost all of them have at least one bug that impacts us. We generate Java clients, Java server stubs, and TypeScript clients. You should expect to be overriding some of the templates to suit your own purposes. Even if it's just to keep dependencies more up to date than this project does, this is not a "run this jar and forget about it" project in my experience. My personal opinions
|
|
That's a very valuable response, thank you very much! I hope there will be more users reporting in. |
|
@black-snow You are definitely not alone. I have exactly the same problems as you and I don't understand how people use it to generate the api clients (java, spring boot, openapi-generator-maven-plugin:4.3.1). |
No it isn't. IMO having issues open is much better than letting bots close it after 3 month. Issue is an issue, and it doesn't just expire because some time past since it was opened. Probably a lot of these issues are duplicates, incorrectly used tool or question that just do not get answer, or were simply fixed without closing the issue. Recently had a discussion with one tech lead who decided to use react-native over flutter, because react native has less issues open on GH. RN automatically closes issues after some time, Flutter doesn't. It's a psychological bias, it's up to you to fight it.
These are real issues. Unfortunately openapi is a massive project with huge complexity. Not all config options can be tested. I remember seeing some progress being made on this front = using most complex schema to test all generators. It's a process. Not all generators are mature enough to support it, many will produce code that doesn't compile, so it's a step-by-step process. If you encounter an issue, add comment to it, add your example. The better documentation of a bug, the more likely it is to be resolved soon. I've seen many complex OSS that do a lot of things and to put it softly "aren't good at it". When OSS gets big community, community concentrates on developing as many features as possible, sacrificing quality. This tool is from developers for developers. Devs can't test properly, do not do QA, do not like maintaining software once its identified with bugs. I advice maintainers (in general) to put a hard stop on accepting new features until xx% of bugs are fixed. Apple did it once, they once made a OSX release that had no new features, but had a few thousands of bugs fixed. Pure bug-fix release would be nice, especially it's hacktoberfest and a lot more contributors with little experience will come. Yes, I've used openapi on a production system, but we used it in a completely different way you described. Business/process analysts had access to our openapi schema. Produced code was packaged as jar, pretty much without any modification, pure generated code. BA/PA/devs and testers were able to modify the file, run jenkins on repo and release it. The generated code was our core of the product, controlling main behaviour with feature flags. Eg. BA could quickly go to the schema, change default value of a boolean, deploy code and see new behaviour without asking devs to change feature flag on server instance. |
|
Thanks for your reply agilob. No one asked whether it's good to auto-close open issues or not and 1k+ open issues IS a huge warning sign but let's not start this discussion here, that's not what this issue is about. It's also not about why things are like they are - it's pretty obiously a huge project. The question was if people do actually use this productively (and if yes, how). So thanks for your last paragraph. Was your schema simple enough or do you use another language / generator? Because right off the bat the generated code doesn't even compile for me. |
|
My whole comment was building up to the last paragraph. We used it for something "simple". Our schema was generating over 50 models, a few models were added every month. I find autoclosing issues and complexity of this project important to answer your question.
Whole project was in maven+Java.
Like said before, it's a complex project from developers for developers. The generator you used didn't work, but 60 others most likely work. I understand your disappointment, but what other generators have you tried?
Yes, people use it on production. OpenAPI is also a contract. Small companies use it, seen it in a blockchain projects, I'm sure redhat uses it internally. |
|
@black-snow those are some great questions, and excellent feedback. I know I'm a maintainer, so my feedback is heavily biased and one might consider "advanced usage". I'll explain my use cases and dive deeper into your concerns. My production experiencesWhen I was at Expedia, I used swagger-codegen generated code and later openapi-generator generated code (after we forked the project) to generate a Scala Finatra client in a Spark Structured Streaming application. This was a custom generator because our project doesn't include a Finatra output, and we had internal observability tools which I had to integrate into the code. I also used the JavaScript node.js client generator to generate contract tests which we ran in the backend API pipelines for my team on every build. Just before I left Expedia, I'd written a custom generator to generate some pact tests with a goal to replace the node.js contract tests. There was nothing wrong with the tests, my team just wasn't comfortable with JavaScript-based tests so we were moving to JSON-based tests (I know… don't ask me). When I started using the generator, my team had 7 APIs which totaled around 40 endpoints and maybe 200 models. When I left there were only 3 APIs but 2-3x the endpoints and models. The Scala Finatra client code was running in production, and while the other code was test code it was integral in getting other code to production. We didn't use generators to generate our server code because: 1) our codebase had a more complex architecture than the standard controller/service type of output you'll find in our generators 2) we were not following spec-first development. My current employer uses OpenAPI documentation for spec-first development across all APIs - of which there are 100s or maybe 1000s. I plan to work with an internal team to integrate OpenAPI Generator into some of our internal tooling to simplify client/server/doc generation for the entire company. Are others using it?Absolutely.
Also, as @agilob points out, it's best to have a ton of issues because it shows there are a ton of users. It also means we're not just randomly closing issues because we don't hear back from people for a couple weeks. The issues are the project's backlog. Just think what would happen if you went to work tomorrow and started deleting hundreds of Jira tickets because your Project Manager hadn't commented on them in two weeks. I could never understand how projects mark issues as "stale"; something is either an issue or it's not. Just like we can't wish away Coronavirus, we can't wish away the technical debt in open source. There's another reason why we have so many issues, though. Many of them are already fixed as a matter of course and we sometimes don't close associated issues until a release has been completed. Many of our issues are duplicates where people don't realize that one or more issues are describing the same thing. Some of the issues don't follow our issue reporting guidelines (no sample inputs, no expectations, no generator version). More still are a result of the user trying to generate against an invalid or incomplete spec document, which is not something we support. Interacting with all of those issues takes time. In fact, at one point our core team was collectively spending a few hours a week just labeling issues and pull requests. This drove me to write a labeler github app to reduce our maintenance overhead. That worked, but since it's a hosted GitHub app, it came with its own maintenance overhead... so I wrote a labeler GitHub action instead. Yet another reason why there are so many issues is time. Everyone who contributes to this project does so in their free time. We have to manage our time between new code contributions, reviewing pull requests, and community engagement. I'd read somewhere that more than half of open source contributors spend 5 hours or less a week on open source. I usually average closer to 10 hours a week. I think a project this size with the amount of contributions made and merged on a weekly basis would be considered "very active" in open source. Your linked concernsYour linked concerns are very valid. I have been working for over a year on Project 5: Simplify Contributions and Improve Usability I've also spent maybe 100 hours or so organizing and creating developer-facing documentation at https://openapi-generator.tech/ which explains usages and provides examples for using templates and fully customizing generators. It's important for folks to read these docs, and they can always use some additional love. Unfortunately, most developers don't really like writing docs (myself included). And since this is a community-driven project we really do rely on contributions from the community to help improve things for the community. I hope you don't mind if I use you as an example related to documentation… I mean no offense it just shows the issues around open source and our reliance on community. You'd referenced our docs in #7479, which you begin with:
The gradle section of the docs ends with:
See below:
The plugin README links directly to the readme within this repo from which the gradle plugin is built. That readme lists all available options. The
I'll admit that I don't consider myself a technical writer but I do try to make things as clear as possible when communicating concepts. Unfortunately, I have "expert bias" as a core contributor so it's often difficult to write docs as if I'm a first time user. We rely on issues and bug reports from users to improve these. When a user raises a concern like yours, it indicates to me that the README link for the plugin probably also needs to be included closer to the first example. As another example, your question about why some configs are not nested within Your comments about "doing something wrong"You're not doing anything wrong. I think you are approaching code generation tooling as if it'll output production-ready code which will fully suit your needs, and that this approach is frustrating you. That assumption is sometimes not the case with code generation tools which are bound to dynamic user-defined inputs. In many cases, our clients will just work right out of the box for maybe 95% of the use cases (see our ruby, kotlin, C#, and aspnetcore generators, for example). In some instances, the code may require template customization as others have mentioned above or it may require workarounds or older versions. In your case, specifically, I think you've experienced frustration because you're targeting Gradle builds and a generator which isn't as active as others. We have an extensive regression testing suite. While we can't possibly test all the combinations of code, we do run full compilation tests on:
So, for every build we run maybe 200 minutes of builds, tests, and integration tests which verify outputs of 100+ generated sources. But as many of our JVM languages output Maven POM files and our project uses Maven, when we execute these samples in our CI it will execute the Maven POM in the sample. This allows for some bugs to slip by in gradle build files. Unfortunately for us, these often go unnoticed because people are probably not even relying on our build outputs in the first place (i.e. generating models/apis/docs into an existing project). My recommendation would be if you're trying one of the generated outputs and Gradle fails, compare it against the Maven POM (or even attempt the build with Maven). If it still fails, then it's a bug. We will often fix the bug and add the generator to the list of compilation checks with the other 100 or so generated outputs. But I want to be clear - and this echos what others have said - you should expect to do customization. CustomizationThe thing that sets our tool apart from others is the customization. Our built-in templates are all mustache. We support handlebars as well. We also support custom template engines. If templating doesn't suit your needs, and this can happen if the data bound to templates doesn't quite match your expectations, you can write a custom generator. Until within the last couple of weeks, you were limited to generating only those templates which are known to the generator at compile time. For version 5.0.0 we'll be able to define completely new templates externally via configuration files like those we use for samples; this will be available for built-in and custom generators. Getting HelpI hope my response was informative and answered most of your questions. You can always reach out to our Slack channel if you get stuck. There are almost 900 users in our general chat and people often get responses from users. You're also likely to get quick responses from me on there as well. Someone could at least guide you in the right direction if you're beginning to feel frustrated by any part of the tooling. |
|
@jimschubert thanks a ton for such a thorough reply. Also thanks for pointing me towards the plugin's readme. I've actually found it in the meantime. And a last thanks for putting so much efforts into this project. It's an important tool for anyone doing anything with APIs, I think, and has the potential to save kajillion of hours and repetitive work. Aight, let's get to the issues and how to resolve them. I have almost no spare time for the rest of the year but I'll happily contribute wherever and whenever I can. Is there a special reason for the Gradle stuff not being tested? Any actual blockers?
But that's hopefully due to the size of the project and not some kind of a goal. Well, depending on what you mean by "customization". For me it's bugfixing, circumventing and failing right now. If the generated client code uses Gradle 2 and some 2015 dependencies I might be able to live with that as long as it works but it doesn't even compile. I don't even need the whole client code, the models would suffice but they weren't correct either (mostly due to lacking support for For me, right now it'd be enough to have the models generated. Writing them manually is very laborious and error prone. I had to write a custom deserializer for the @IlyaLoshchinin Thanks for reporting in. Sadly no. I'm doing things manually now since the project's schedule is tight. |
We regularly timeout on our CI builds. We just don't have the resources to build all permutations of build systems and output options.
Regarding customization, this should really be the goal of most of our users I would think. You won't need customization if you genuinely don't have additional observability needs and your target APIs are not very complex APIs. You likely won't need much customization for many of our client generators. You will need customization of some sort if:
|
|
Sure, but I mean it should just compile and work in a vanilla way out of the box. (Which it does not for me atm.) Alright, I guess I'll close this and report the issues I encounter. Thanks everyone. |
I think you just got unlucky with version of generator at this time. It works most of the time ;) |
Just want to add that we also use the issue tracker for feature requests, announcements, and of course issues as well. In other words, not every single issue is a bug report as it could be a feature request or just discussion. |
|
I do understand there's a lot of work put into this and I don't want to insult anyone putting in the time into what is, ultimately, an opensource tool. I have been struggling with various issues with the Java generator for days now, in two different projects. There is no way to make it work, even for a very basic project. I am trying the Maven 5.0.0 generator and it just doesn't work. There's almost nothing I can do about it except apply hack upon hack to get it to even compile. Maybe I'm just doing something wrong, but I've been trying to get a basic setup running for 2 days now and I just can't. |
|
@CGavrila - I think your statement is too broad.
I personally contribute to ~4 Java projects that use many different versions of the generator and 2 TypeScript projects. They all work today, albeit with compromises in some places. The generator absolutely has difficulty with sections of the OAS, and some functionality is not available. One of the common tripping points is that there's a particular design imposed by OAS/this generator that may not be exactly what you want to express. E.g. if you're heavily doing RPC APIs or dynamic responses, it's really not a good fit and you're going to fight every step of the way.
It'd probably be helpful for you and others to be specific - are you running into existing bugs? Are you running into erroneous behavior (i.e. you should open a bug)? |
|
I needed to generate some java and python from the oas. So ... this afternoon I had some free time... I was able to get a gradle build generating model files from an OAS in about 5 or 6 hours work. What I'm getting at is it's actually not at all hard to roll your own and I dont' buy the value proposition of this product anymore. |
|
@Johnlon are you gonna os it? |
|
@black-snow I'd love to but can't for reasons outside my control. OSS'ing it would only be to demonstrate how easy it is, because the gist of my recommendation is to roll your own. The only hard bits to figure with the swagger parser API is figuring out the right way to walk the data model (properties, $refs, allOf) to construct the fields and classes. One decision you might want to make is whether you model single inheritance and how, eg as an allOf. If you do, then fine you can map a SINGLE allof to an inheritance relationship in the generated classes. This inheritance can be useful for statically typed languages as you can then write code thanks operating on those higher abstractions in the model of your API. Hazard... If you have self referential data structures then sometimes flattening and following $refs will fail with a stackoverflow. You can see this same thing happen inside things like the swagger resolve routines... The conclusion I've come to is this.. Use case 1: Use case 2: I am an org building internal facing client sdks for my internal clients who are using a handful of Lang's used in my org. I will probably have corporate stds (or influences) on the features and arch of these APIs. For support and evolution reasons I will want consistency across these impls so again I need to support a narrow specific Lang's and no compromises. So I will roll my own. Use case 3: I am a client of many services and I probably only have one language in my system. I want to bake in a set of features (eg telemetry / failover) to those sdks without compromises . I only have one lang to worry about and want that customisation Use case 4: I'm a random party on the internet wanting to generate a client side in a single language for some random service and Im not too concerned about features and consistency. I can't be bothered writing my own gen for this one off use case. So I use OAG to get bootstrapped and if my needs evolve then I can always change my mind on approach later. Thoughts? For me OAG is possibly ok for initial prototyping but more muture orgs will rolll their own with no compromises. Having spent 50+ hrs figuring out the whole model passed to mustache and discovering that the java code behind each gen has significant differences on decisions on type mapping (that I disagree with) , and inexplicable differences across APIs even for variants of a single lang (eg Py) then it's clear that there isn't really any governance and consistency and generated code sometimes doesn't work (see above), and the name mangling and lack of support for idioms like subpackages for organising the generated code or big models. I think fine to get you going , but once you need something even slightly different or better or less buggy then PLEASE don't do what I did. Sunk cost fallacy.. I lived with thus thing for 18months with its shortcomings. I then recently decided I couldn't bear it anymore and tried to make things better, and spent AGES learning the detailed inner guts of this thing and discovered unhappy things , and made PRs that led to lots of debate and delay and eventuality I deleted the PRs. Then last Friday evening I realized enough was enough and then wrote a 100% spot on impl of my own in about 100 lines of groovy including the templates. (Last Friday I wrote the java gen and used Lombok to make the model code really terse, to aid visibility of the model, this week python, next week the world!). I feel there are probably a lot of folk like me thinking well there's no competition out there surely this is as good as it gets, and end up living with it for way too long. Hope this helps. |
@black-snow I am currently working on Fern which aims to improve the devx related to defining APIs and generating server/client interfaces. Fern is open source as well. |
|
Yeah I really thing we need a cleaned extensible framework that's has not
been hopelessly compromised by its sdlc and code quality issues.
Better curation.
One that isn't creaking under a mass of broken (or nonexistent) slow tests.
There really isn't anything out there for oas that I want to use.
Worse tho , the oas is hopelessly inadequate in itself to describe APIs in
the manner needed to generate anything other than the controller skin. Need
something more expressive or just come up with a ton of OAS extensions and
DIY
…On Sat, 23 Jul 2022, 9:04 pm Deep Singhvi, ***@***.***> wrote:
@Johnlon <https://github.com/Johnlon> are you gonna *os* it?
@black-snow <https://github.com/black-snow> I am currently working on fern
<https://docs.buildwithfern.com/#/> which aims to improve the devx
related to defining APIs and generating server/client interfaces. Fern is open
source <https://github.com/fern-api/fern> as well.
—
Reply to this email directly, view it on GitHub
<#7490 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAGMFGDLMI4C3L434ZI6B4LVVRF4HANCNFSM4RW4HS2A>
.
You are receiving this because you were mentioned.Message ID:
***@***.***>
|
|
Hi @black-snow, your question and the further comments it gave birth to were really helpful for me to understand where I stand. You are not alone. |
|
@NathanFlurry thanks for informing us there's another generator/spec available out there. As we told the author of another generator in our Slack channel before, we're not against any other specifications/generators but this is not the right place to market other specifications/generators so we've deleted your message. |
This may sound like a rant but that's not what's intended. I'd actually like to know if people successfully use this tool to generate code that runs in production because my experiences are pretty bad so far.
The first issue for me was: okay, there's swagger codegen that has 2.5k issues and then there's this fork which also has 1.7k issues. That's a huge warning sign already. But look, there's a ton of generators and things it does so that might be okay. But which one do I use now? I tried both and the results were the same.
I haven't tried the other generators. Maybe I'm the only one trying to generate client code for
javaandresttemplate. I have a bunch of issues. Unclear docs, Syntax errors in the generated gradle, missing dependencies in the generated build.gradle, array withanyOfis not supported - I have to manually add a parent type and let the subtypes extend this, I have to explicitly setopenApiNullableto true in the gradle plugin in order to have the dependency added although it defaults to true (according to the docs). And after all of this I still cannot use it because some nullable field fails in my spring appdespite the config being set up.
Again, please don't get me wrong. I'm sure that lots of effort has gone into both projects. Maybe I'm just doing something wrong? Although OAS 3.0.3 is from February the original 3.0.0 is quite dated. I can't imagine that the generator just does not work - I mean, it's version 5 already.
For my current project my idea was to go spec first and have the client generated with a single button click. OAS isn't new anymore so the tooling should be good by now. But now I've invested some days without success and I guess I'll have to fall back to manually annotating my POJOs and stitching stuff together with Restteample or Retrofit myself.
The text was updated successfully, but these errors were encountered: