There are a lot of benefits for the API producer in terms of tooling and the ecosystem.
But that tooling also helps the consumer. Look at all the tools listed here: https://openapi.tools/ Those that would be helpful to me as a consumer of an API are:
* Documentation
* Learning
* Mock servers (for testing)
* Some of the tools under misc
* SDK Generators. Most people don't want to consume an API using REST, they want to use their fav language to do so
SlateDocs looks really nice, though. As sibling comments have pointed out, you can have both.
For people who haven’t clicked the link, this assumes you’re defining your API in OpenAPI/Swagger/a few other options, and (one directionally) converts it to suitable formats for static publishing:
Widdershins is generally used as a stage in an API documentation pipeline. The pipeline begins with an API definition in OpenAPI 3.x, OpenAPI 2.0 (fka Swagger), API Blueprint, AsyncAPI or Semoasa format. Widdershins converts this description into markdown suitable for use by a renderer, such as Slate, ReSlate, Shins (deprecated) or html suitable for use with ReSpec.
I containerized it and added some wrapper scripts so we can just drop the YAML spec in our repo and have build automation to generate/deploy a web site with all the relevant docs.
Mostly familiarity.
The OpenAPI spec and the Swagger tools are something that a _lot_ of devs are familiar with, and they integrate well with lots of other tools (We have OpenAPI docs embedded in out Confluence/Jira workflow).
That SlateDocs looks nice, but I've never heard of it before.
If I had two browser tabs open to evaluate different 3rd party APIs to consume, I'd somewhat strongly lean towards the one that used OpenAPI, because I know it'd fit in with our existing toolset and experience.
But yeah, totally right on the “feeling at home” idea.
The most important aspects of good API documentation are
1) correctness,
2) thoughtful and complete examples, and
3) a clear explanation of the data model and state transitions.
These can be accomplished with any tool.
If it's something like Stripe (payments), Plaid (collects bank credentials), or Lob (sends physical mail), you definitely need a sandbox beyond the MVP stage. At one point we had a pre-launch payments API at Square and we provided partners with prepaid debit cards to test with, but that approach obviously doesn't scale well.
Another huge benefit of sandbox APIs is that people can use them for CI when testing their own integrations.
Still, when the cost of creating and manipulating objects in the production API is negligible I would say a sandbox is unnecessary.
As for how much persistence is needed in the sandbox, start with what is easiest to implement and gather feedback from your developers.
Be aware that developers often throw out ideas of API features that would be nice to have without much though about priority of effort involved. Sometimes they ask for something and then don't get around to updating their integration to take advantage of it.