Background
OpenAPI is a standard for documenting API resources. Libraries like Spex allow you to generate OpenAPI descriptions of your endpoints to share with consumers. Then, the OpenAPI community provides a series of code generators that take the API descriptions and create client code (for example, one function per API endpoint). They even support Elixir.
However, I was not satisfied with the code generation options available for Elixir. I craved more flexibility in the outputted code, and better ergonomics of the resulting libraries. Being written in Elixir would also be a bonus.
So, I created OpenAPI Generator for Elixir. It accepts an existing OpenAPI description and generates client code for the API endpoints.
What does it do?
After installing the project as a development-only dependency and adding your configuration, it provides a task mix api.gen which accepts an OpenAPI description document and writes formatted code inside of your project.
The generator aims to be highly configurable, allowing you to repeatably rename, merge, and ignore parts of the OpenAPI description. This way you can create more ergonomic client code regardless of any weird parts of the original API description. For example, GitHub’s OpenAPI 3.0 description had to make use of NullableRepository and other repetitive schemas that would only confuse users of the client code. Such a schema can easily be merged into the Repository or FullRepository schemas. (Also, those two schemas could be combined into two typespecs with a single struct definition.)
With this kind of careful configuration, client code maintainers can create libraries that have the ergonomics of a hand-crafted library while also keeping the maintainability of generated code. GitHub, as an example, has too many API endpoints to maintain by hand — but we shouldn’t have to sacrifice usability for the sake of automated code generation.
Learn more
Check out the repository and join the discussions tab with thoughts and feedback.
11 Likes
I have taken a look, though not a super detailed one.
It did seem to me you only support httpoison? IMO a huge selling point would be the ability to choose which HTTP library you want supported, including with extra options a la Finch that also needs to know pool sizes and such.
I like the intermediate layer of abstraction, though I do wonder whether it might have a performance impact. Likely not.
I think you may be confused about the relationship between this project and the code it generates. This is something I will work to clarify in the readme and documentation.
This OpenAPI generator project is responsible for creating two types of modules: schemas and operations. In the example GitHub client, these modules can be found in lib/schemas and lib/operations. Everything outside of these directories is not generated code.
If you look through the modules in those directories, you will find no references to any HTTP client at all. In fact, the contract is a very general call to client.request/1, where client is a module configured or passed in as an option to the API operation. It is expected that a client library author (the customer of this project) will define their own client module using whatever tools they see fit.
In the GitHub client example, I’ve deliberately created a bring-your-own library system where anyone can define plugins to use any HTTP client they wish. It just so happens that I’ve only written an HTTPoison client out of the box for now.
2 Likes
I highly disrecommend going the codegen route on this,my experience is it becomes extremely finicky to get deployment and code control right on this, tbh this is a strong case for macros. Full disclosure, I was planning on doing an OpenAPI client compiler immediately after I finish my server router compiler, if you want to collaborate dm me.
2 Likes
Thanks for the feedback. I decided to go this route for various reasons, and I’m quite happy with the results so far. You may have different needs, or intend to use the client code in a different context (directly in an application instead of as a separate client library). There’s room for all of these methods in the community.
1 Like
I’ve worked on a Stripe SDK (Stripe — Striped v0.5.0) though the code is now merged with the StripityStripe library. It generates the code from the api spec at compile time.
Also found that it is finicky, all public open api schemas seem to do things a little differently if you want to generate an idiomatic sdk. E.g Stripe doesn’t use the tags functionality of the spec which would have been useful. So, the customisability your library has is a big plus here.
2 Likes
I’m pleased to share that I will be discussing this library at ElixirConf US 2023 in a talk titled Filling the Gaps in the Ecosystem. The initial schedule is below (subject to change):
Date: Wednesday, 6 September 2023
Time: 2:15pm ET
Location: Palm AB
Would love to see and chat with anyone who uses this project. And if there’s anything you’d like to hear about in the conference talk, please let me know!
8 Likes
