[question & advice request] Generating an API client from an OpenAPI spec

[kipcole9]

Based on the Elixir Forum discussion around payment gateway support I thought I would look at building an API Client for Stripe. Since the Stripe API is built on OpenAPI it makes sense I use this to generate the API Client.

I investigated using open-api-generator but the Elixir generation isn't perfect and the Elixir template maintainer has abandoned the project (confirmed with him yesterday).

I recognise that open_api_spex is about building API Servers but there is symmetry with the API Client side of course.

What advice would you give me that I should consider as I start on this journey .... (or suggest a different forum to have this conversation)

[mbuhot]

Hi @kipcole9, generating the API client from the OpenAPI sounds like the best way to get a lot of API coverage quickly 👍

Some considerations:

• How will the operations be grouped into elixir modules? The Stripe API doesn't seem to have tags on the operations for grouping them. Maybe some hand-written mapping of path prefixes to module names is necessary?

• The Stripe API appears to use inline schemas for the request bodies and parameters, and named schemas for the response bodies. This makes it difficult to define structs for the request parameters. You could define a struct for each operation named using the operationId, although it doesn't capture the structure of deeply nested object request bodies.

Looks like @mrmstn has contributed to open-api-spex and open-api-generator, any suggestions for @kipcole9 ?

[mrmstn]

Oh, well thank you very much for thinking of me 😀!

@kipcole9, @mbuhot is with his findings absolutely on point. The elixir generator of the open-api-generator depends on the tags for building the API Modules with the different actions (which are the operationId). Since the Stripe API doesn't have those things specified you will end up (or already did) with one API Module Default with a looot of function which do not say anything about the actions itself.

Also, the "anonymous" aka inline schemas should also have a title attribute. The generator will use this field to generate the struct for the de/encoding.

Since I'm part of the elixir tech. comitee of the open-api-generator, I'm glade to improve the client. Just open a issue over there and add me as cc if you found some bugs. But keep in mind, the generated client can only be as good as the spec it is based on.

My suggestion would be, add the title attributes to the inline schemas and group some operation in tags to break down the file size, your editor will thank you. Since the operationId is only used once in the whole client, you could change it in elixir later on or do it in the same way as you added tags to the operation (which is better, but more frustrating). if you change them in elixir, keep in mind that regenerating the client will overwrite those chances

And hey, only change the things you really need - every thing else can be deleted afterward, otherwise this will take a huge amount of time (and motivation) 😁

I'm pretty sure others would also be interested in those changes, so maybe, just maybe, Strip will make those changes for you - or you could merge them back with tags, titles and operationIds as soon as you did them by yourself.

[kipcole9]

@mrmstn, @mbuhot Thank you both for taking the time to respond and for the level of insight.

I ran the Stripe specs through openapi-generator -g elixir and the resulting code did not compile. It could well be related to your comments about the completeness of the Strip spec. My conclusion was that I would write my own generator for the Stripe API which would allow me to overcome some of the limitations. Since this API changes (or enhances) frequently I don't think I can afford to hand modify the spec each time.

Its not that I'm motivated to write a generator - happy to collaborate with the team on openapi-generator for Elixir although being a non-Java person that might be quite a challenge!

[janajri]

@kipcole9 any updates on the idea you outlined above? I'm looking to generate a client for a 3rd party openapi spec.

[mrmstn]

Hi @janajri
if you already have a good 3rd party spec and don't want to generate a extra client lib, this project could be something for you: https://github.com/teamon/tesla-openapi-examples

[kipcole9]

@mrmstn, thanks for chiming in. Since you announced your project, I'm all in on that approach. I haven't had time to dive in deeply yet but I'm sure hoping you're take it all the way since I think its a really good strategy for open API client integration.

[janajri]

@mrmstn this is exactly what I was looking for 🙏🏽