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.