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.
So…
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.
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.