Hello,

Long abstract

I made a first post 10 months ago about my project, and my beginnings in programming.

So I’m creating a project from scratch (since about 10 months, with 3 months dedicated on totally other stuff).

I am accompanied by my brother, who is a master full-stack developer (in my eyes, but not only). But he doesn’t get much time, since he is already full-time working for a company, and already have a great professional investment with them.

He guides me on the app architecture, then I write code, push commits and merge requests that he verifies, send me questions and comments back, and so we advance like that.

So we chose Elixir as a programming language, with Phoenix as a framework for the backend. And because the projects turns to be a (native) mobile app at first, we chose FlutterFlow to design and get the frontend quickly working. Then we will be able to get all the generated Dart code from this low-code tool, and to polish the frontend regarding our needs. But it’s not at all a priority for now, as we can get things working fine in a simpler and (most importantly) faster way.

We’ve advanced on backend code, and I learned a lot (and still have a loooooot to learn) about programming.

To be honest, programming is still not a passion (as it is for my brother), but a mean to achieve my vision through a concrete project. But I also admit it can be pleasant to code when you find solutions to problems you encounters, and learning new things everyday is a pleasant journey (but it don’t makes you live, nor makes the world turns better).

Short abstract

We’ve creating a project with:

• a backend using Elixir - Phoenix
• a frontend using Dart - Flutter (currently FlutterFlow to gain time)

The frontend communicates with the backend and receives responses through a JSON REST API.

As it is painful to modify API calls on the frontend (even more in a low-code tool I guess, because a lot of actions are done with clics on an interface, so you can’t easily search/replace), we want to stabilize the API.

After researches with my brother, we decided to rely on the JSON:API specification, which looks very complete, to avoid too much thinking on what we need now and should need in the medium-term.

It is also important for us to have a good API documentation for 3 reasons:

• it is faaaaar easier to integrate API call definitions to FlutterFlow with an OpenApi / Swagger file than without (OpenApi 3.0 required)
• it is a good mean for us to visualize the current features of our API
• it would be useful in the future if we want to share our API with third parties

After other researches, we found tools that may be useful to our project:

• PhoenixSwagger → to generate API documentation
• Bureaucrat → to generate API documentation
• JSONAPI Elixir → to generate JSON:API documents

Questions

What do you think about our API strategy?

Do you have experience / feedbacks on currently using one or many of these libraries?

Do you have other experiences to share on using JSON:API specification on Phoenix?

If we go this way (with these libraries), does some of you already updated PhoenixSwagger to generate OpenApi 3.0 documents instead of 2.0?

EDIT: I’ve just seen this post OpenApiSpex - OpenAPI / Swagger 3.0 for Plug APIs that I haven’t seen in my previous researches. I start to read it. All feedbacks on my case are still very welcomed