this is an open question to all of you out there creating web applications with APIs. How do you go about documenting your APIs?
Do you generally prefer to use frameworks such as Open API/Swagger or API Blueprint, or do you typically go with something completely different?
And how do you go about it in Elixir/Phoenix specifically? Are you using any additional Elixir libraries such as PhoenixSwagger, BlueBird, or Bureaucrat? What has your experience with them been?
I’m looking forward to hearing about your experiences
Imo you should write out your openApi specs, document that, and generate a Phoenix router from the spec. Currently there is no publically available library for this, but I am currently testing this out at work and we have plans to open source it once we are in prod, which is soon.
I’ve never created an API with Phoenix, but I’ve created a MQTT API that is documented with https://www.asyncapi.com which is great. What I was missing when I made that was a way to automatically check the payloads coming in (JSON) vs a schema. So I wrote that myself and it works really fine. The thing gets the payload schema from the asyncapi spec for the incoming MQTT-topic and automatically validates the payload. Is there something like this for Phoenix?
@sebb disclaimer: self-promotion if you want (almost complete) JSONschema validations you can use Exonerate - JSONschema validator for elixir. As far as I know this is the only library that codegens the validation logic at compile time and thus doesn’t have a huge footprint on your delivered package and also is very fast.
I’m with you on this one. I’ve done spec-first and it has worked great. Putting the benefits of early feedback to the side, you can use a JSONSchema validation library and actually share object definitions between the schema and the application and use them in contract tests.
At a previous company we used PhoenixSwagger + Bureaucrat with a custom formatter that would output markdown which finally fed into a static site generator.
I find realistic examples in the docs much more helpful than schemas alone. A postman collection with working examples is also nice to have.
I have been working with your open API library on an application in our company. So far I really like it.
One thing I wanted to ask you was if it’s wise to carry the open API %Schema{} struct around from the application layer (controller) into the business layer (lib).
My inquiry is prompted based on reading an existing application written by another team which I am now the owner of, and finding really awkward to not able to add data to these schemas inside the business layer.
I like the idea of having structures in the application layer to document the intake and output of an API to the external world, but beyond that, once the request lifecycle flow reaches inside the business layer, it seems like these schemas should no longer be used since they have served their purpose, and only in application’s view layer should the output schemas be prepared before finally dispatching the response.
In my application, the business and the API layer are fully separated. The Open API schema is part of the MyAppWeb namespace is not used in any way in the business layer.
You can take a look at how this is done in Keila here: keila/lib/keila_web/api at main · pentacent/keila · GitHub
