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 :slight_smile:

3 Likes

Hi, here is PhoenixSwagger example in production:
https://testivator.com/api/doc/index.html

2 Likes

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.

4 Likes

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?

3 Likes

@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.

3 Likes

APIDOC has Elixir support, works for us https://apidocjs.com/

1 Like

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.

2 Likes

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.

3 Likes

How do you do contract tests?