wmnnd
Your Opinions on Documenting HTTP APIs
Hey folks,
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 
Most Liked
ityonemo
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.
ityonemo
@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.
Sebb
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?
Popular in Discussions
Other popular topics
Latest on Elixir Forum
Sponsor Spotlight
Supporting innovation across the BEAM ecosystem.
Categories:
Sub Categories:
Forums
Popular Tags
- #ecto
- #liveview
- #troubleshooting
- #learning-elixir
- #deployment
- #library
- #erlang
- #testing
- #genserver
- #mix
- #absinthe
- #remote-other
- #otp
- #plug
- #how-to-question
- #macros
- #postgres
- #channels
- #elixirconf
- #exunit
- #discussion
- #code-sync
- #javascript
- #podcasts
- #onsite
- #dialyzer
- #docker
- #authentication
- #umbrella
- #full-time-contract
- #podcasts-by-brainlid
- #ecto-query
- #elixir-ls
- #phoenix_html
- #iex
- #blog-post
- #graphql
- #genstage
- #ai
- #websockets
- #supervisor
- #advent-of-code
- #elixirconf-us
- #distillery
- #processes
- #forms
- #api
- #metaprogramming
- #security
- #performance
Our Sponsors
Build Elixir applications with speed and confidence.
Supporting innovation across the BEAM ecosystem.
We build reliable cloud platforms for business-critical systems.
Catch errors, track performance, monitor hosts and more.
Real-time error tracking, performance insights, and observability for devs.
Develop your skills with books, videos, and courses.
Producing high quality Elixir screencasts since 2017.
The deployment platform built for Elixir: PaaS ease, VPS control.
Courses that'll move you from confusion to "Aha, now I get it!"