Hacker News Reader

Comment by twodave | Hacker News Reader

I reviewed Slate for one of my clients' private APIs. We ended up using Postman's API docs instead. The logic that brought us to that point were:

1. The ability to generate/sync documentation from a Postman collection meant we could write our test suite and documentation in one step.

2. Since we were already paying for a team account, adding Postman documentation was practically free.

3. Environment variables. We could write our test suite with one set internally and then publish our API docs with another set.

As someone else pointed out, it's possible to generate Slate documentation from an OpenAPI spec, but to me Slate on its own leaves a lot to be desired.

View on HN

I just recently went with Postman's API docs for these same reasons. Having used Postman to test while building out my API, it was refreshingly easy to take the extra steps of doing everything "properly" – fleshing out the rest of the variables by pulling out any static values, creating extra descriptions in Markdown, etc – in order to publish it as living documentation.

Correct me if I'm wrong but if you use swagger / open API you can abstract out your docs and they're portable?

For the project I'm talking about there wasn't an existing swagger implementation. The bottom line ended up being that since we had tests in Postman anyway, generating documentation became a few small steps (Add nicer descriptions for folks outside the org to consume, then click a button basically).

Can elaborate what you need exactly and what Slate does not offer?

From point 1 it sounds like they already use Postman for testing and so using it for documentation makes it easier - perhaps its somewhat automated.

Honestly, like all decisions, there were many factors. A big hurdle in this instance was that the existing application was written using a PHP framework that made generating something like a SwaggerDoc an extreme pain. Since we knew we'd have to write documentation outside the product anyway, and we were already using Postman for tests, using their (free, and already hosted someplace) docs was a no-brainer. It even allowed us to share the docs with 3rd party developers in a way where they could import the docs locally and run them -- again, via Postman in order to test their own uses of our API (simply by setting up a few variables like putting in their API key).

Reply on news.ycombinator.com