Generate Elixir API from Swagger / OpenAPI 3.0

I’ve done quite a lot of research in this area - to the best of my knowledge no such tool exists. It would be very useful for migrating an implementation written in JavaScript, Scala, Python or whatever to Elixir.

Strikes me it wouldn’t be the hardest thing in the world to write. Parse openapi definition, generate the structs and stubs required by openapispex then fill in the blanks. @moxley might have some thoughts

Thanks @bryanhuntesl. I did think there wasn’t anything around, but thought it was worth posing the question.

I did some experiments around this kind of work a couple years ago, but didn’t get very far with it. The focus was on generating clients, and server stubs were an eventual goal.

For what it’s worth, there’s an Elixir “backend” in the openapi-generator, introduced back in 2017, and still alive – there’s a recent PR open from an early July 2022 by @halostatue)

I tried generating Elixir app from a OpenAPI spec provided in openapi-generator’s samples. Generation works. The generated code doesn’t look like Phoenix API though. I didn’t test it further, e.g. running an actual API server to see if it behaves as expected.

It’s not exactly an answer to generating a “Phoenix API”-compatible Elixir code, but better than nothing (I guess).

On a second view, scratch what I said. It’s a client code generation

To give some perspective. It is also difficult to keep this in sync with the openapi spec over time. Also, the generators get old very fast. From my experience from using this in java. We had more trouble with the generator. Instead, we built it manually and programmed unit tests to check that the implementation is in sync with the openapi spec.

And also the spec is quite complex as this is using all features json-schema has to offer.

Thanks for the mention. The opened client PR is about to merged, so that is a good thing.

I’d be happy to spend some time talking with someone on how OpenAPI generator could be extended to provide a server generator. There’s a few things noted in the documentation as “not compatible” in Elixir that make no sense to me, but that’s likely resolvable.

Even though the OpenAPI generator is written in one of my least favourite languages (Java), I found the codebase to be eminently approachable and entirely runnable in Docker so that I didn’t have to have a Java development environment set up.

It looks like the PR still hasn’t been merged, are the clients generated by the current release (not including your PR) usable/production ready or do you think it is better to wait for the PR to be merged before getting started?

The PR in question is the second of two, and the first was necessary to make the Elixir clients baseline usable again (certain things had drifted). This PR is more of an improvements PR that makes for better clients (the generated code looks more like what is expected, and requires less change when running mix format; the current released version will have more drift).

There are more changes that I would want to make based on the last several years of using Tesla and Elixir:

1. Entirely remove the Tesla compile-time configuration, except for the adapter (and I’d probably make it easy to override that at runtime).
2. Implement a behaviour and default implementation of request token authorization caching (use an optional con_cache dependency and detection of same).
3. Look at other generators to see if unit tests using Mox, Tesla.Mock, or Bypass could be generated.
4. Look over the way that OpenAPI Generator allows for the use of external templates (whether you have to provide a complete template set or can override individual templates, etc.) and improve the documentation on how that could be done on a per-project basis for Elixir, particularly documenting the extensions to the template functions that help with Elixir.
5. Maybe add some combination template functions that cover common repeated cases (e.g., {[#atom}}{{#underscored}}}{{value}}{{/underscored}}{/atom}} could be replaced with {{#underscored_atom}}{{value}}{{/underscored_atom}} or something better.
6. Maybe switch all the mustache templates for elixir to <%…%> pairs instead of {{…}} pairs because the latter really confuse things when tuples are involved (see an example of the latter in README.md.mustache).
7. Make sure that the current restrictions that are listed on the Elixir clients are real. IIRC, there’s about 40% of the features of OpenAPI that are considered incompatible with Elixir; IMO that should be < 10%—but probably requires some explicit understanding of what those features should do, as well as coming up with good template implementations, etc.

Which is to say that, what’s there is good. The PR makes it even better. There’s a lot more work to be done. I suspect that if I do much more with it, I’ll end up as a reviewer on open Elixir tickets.

I have an impl of this and I’m talking to my former boss to get it open sourced. If I can’t get that, I can provide tips if you want to imply your own.

Update:. The library is on its way. I’m currently refactoring the JSONschema stuff to be easier to debug