21–30 of 73 posts
I'm also curious about the reverse direction -- can I generate an openAPI spec from my typescript Api? I'd rather write code than schemas.
https://swagger.io/resources/articles/adopting-an-api-first-...
Earlier quoted context omitted.
I talked to a startup ( https://stainlessapi.com/ ) about a service they provide where they take an OpenAPI spec and build good SDKs on top of it. This included making sure they are idiomatic, included examples, handled exceptions (Edit: like if one SDK consumer needs a slightly different thing because they use a different, custom API, not like network or language exceptions) if needed, and some other goodness. I pas…
I prefer graphql because of this. It's a huge pain to maintain open API files and the generators are of varying quality supporting different specs. They also handle some parts differently in the output. Which generator have you used for typescript? There are 4 of them and all of them have different issues. I find the axios one the most stable but keen to know. How do you also handle refreshing token, incepting reques…
Edit: typo.
>OpenAPI Generator allows generation of API client libraries from OpenAPI Specs It does, but the generated code can be very shitty for some combinations of spec and output language. I maintain Rust bindings for the Kubernetes API server's API, and I chose to write my own code generator instead. The README at https://github.com/Arnavion/k8s-openapi has more details. The point there about bugs in the spec is not limite…
Ultimately built our own generator because we wanted to ensure specific behaviour for status codes in all of our clients.
We also published the generated clients as NuGet packages for our external consumers, the generated clients had the descriptions etc from the OpenAPI spec embedded in XMLDOC comments (C# code documentation) which helps developers a lot because it appears in IntelliSense in visual studio
>OpenAPI Generator allows generation of API client libraries from OpenAPI Specs It does, but the generated code can be very shitty for some combinations of spec and output language. I maintain Rust bindings for the Kubernetes API server's API, and I chose to write my own code generator instead. The README at https://github.com/Arnavion/k8s-openapi has more details. The point there about bugs in the spec is not limite…
I now maintain a separate copy of the templates that implemented some missing features of the spec that I needed, and adjusted access control etc to suit my needs. And I also feel like checking the generated code into source control is the way to go, if only for the build time improvements. I mean it doesn't change often enough to warrant being rebuilt all the time.
>OpenAPI Generator allows generation of API client libraries from OpenAPI Specs It does, but the generated code can be very shitty for some combinations of spec and output language. I maintain Rust bindings for the Kubernetes API server's API, and I chose to write my own code generator instead. The README at https://github.com/Arnavion/k8s-openapi has more details. The point there about bugs in the spec is not limite…
I once mad a stab at fixing it, but i got bored after getting feedback from my WIP PR that made it clear no one cared.
Earlier quoted context omitted.
I prefer graphql because of this. It's a huge pain to maintain open API files and the generators are of varying quality supporting different specs. They also handle some parts differently in the output. Which generator have you used for typescript? There are 4 of them and all of them have different issues. I find the axios one the most stable but keen to know. How do you also handle refreshing token, incepting reques…
It shouldn’t be a pain to maintain OpenAPI files. The same code you write to validate your request/response should automatically generate the OpenAPI see my comment here: https://news.ycombinator.com/item?id=33221395
Many legacy codebase don't have an easy way to add schema and make code changes so you end up maintaining a separate file to avoid making changes in the codebase.
What’s the conceptual difference between this and SOAP with WSDLs?
OpenAPI Spec and auto-generated API clients are very useful when multiple languages need to be supported, like when running a developer program. I've worked at companies that both use OpenAPI Generator for official clients and ones that wrote our own tools for API client SDK generation (with different design philosophy). I've used a number of generators myself to compare and submitted fixes / enhancements to OpenAPI Generator. I used the Go client generator a while back and compared it to others, and recently started using the Crystal one.
To get the most the project, the following is useful: (a) need to support multiple languages, (b) ability to update the generator's code, both in Java and templates (Mustache or Handlebars), and (c) ability to discuss design in GitHub issues and the Slack channel.
The nice thing about OpenAPI Spec is that there is an ecosystem of tooling to support it, including rendering API references (HTML and PDF), API explorers (HTML pages to execute API calls), API clients, etc. But there is a learning curve. For writing specs by hand, I use and favor the Stoplight Studio IDE ( https://stoplight.io/studio ). For programmatically analyzing and editing specs, which is especially useful for finalizing auto-generated specs, I've built an OpenAPI Spec SDK library to make this easier ( https://github.com/grokify/spectrum ).