Phoenix Apis and documentation. JSON API? Swagger?

What advice would you give someone starting to build a phoenix API?

What I am especially interested is documentation I’ve stumbled upon swagger, recently,
partly I like the whole idea, but whenever I am working on a swaggerfile, I just find hard time getting my head around it, and often wonder if it is worth it.

Using phoenix_swagger makes it somewhat more enjoyable and it certainly feels better as it backups as code documentation. However I am still not 100% convinced. I am always getting the feeling I am doing something wrong, and to be honest cant find an example to reference to.

I’ve been also using ja_serializer I like the JSON API standard and its a pretty good serializer. And I am thinking of writing a library to help integrate the two.

What have you enjoyed working with the most for documenting and building APIs? Has anyone tried to use phoenix_swagger and ja_serializer in the same project? And if so what was your experience.


I am also considering GraphQL, but have never tried to implement it or looked at it in depth.
Any comments on that?


I would really recommend looking at the absinthe for GraphQL, it works quite well and easy to integrate into any pipeline.


vasspilka you may find fork has some useful extensions to Phoenix swagger for working with JSON:API.

We found creating the schemas by hand very tedious as JSON:API is highly structured.


I find phoenix-swagger to have too much boilerplate code, it litters the controllers file, is there a better way to achieve this?

You can put all the schema definitions in separate files, then include them in the swagger document from the callback in the router module.

The parameters and response docs need to be in the Controller modules due to the way they are discovered using the Phoenix Router API. You can extract any repeated parameters into functions and call those. Guide

You can put the whole API spec in an external JSON file - but in my experience these require a lot of work to keep updated vs having the docs with the code.

There are some alternatives when targeting OpenAPI 3.0: Rolodex has a nice DSL using doc metadata and OpenAPISpex is a bit like PhoenixSwagger but without the macros.

1 Like