4 ms·
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 abilit
by twodave 6y ago
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.
- karussell 6y agoCan elaborate what you need exactly and what Slate does not offer?
- ssss11 6y agoFrom point 1 it sounds like they already use Postman for testing and so using it for documentation makes it easier - perhaps its somewhat automated.
- twodave 6y agoHonestly, 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).
- adamhowell 6y agoI 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.
- nickthemagicman 6y agoCorrect me if I'm wrong but if you use swagger / open API you can abstract out your docs and they're portable?
- twodave 6y agoFor 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).