dredd

The last thing that scratched this itch for me was Dredd https://github.com/apiaryio/dredd . But writing tests in markdown is not for everyone. Here are few examples of what "test files" look like https://github.com/apiaryio/api-blueprint/tree/master/exampl... I didn't use in for two years so I can't say how well it works today (it doesn't appear to be actively maintained).

Adhering to OpenApi 3.0 spec https://swagger.io/docs/specification/about/ you will be able to take advantage of plenty of tools available to you, regardless of the programming language/framework chosen to build your software. It's not always possible or desirable to have back-end models and controllers auto-generated from OpenApi spec, but still I totally recommend to make an extra effort to keep documentation and API in sync since day 1 as API is evolving. Document an API it's definitely not an easy task, but it pays off - specially if you plan to have third-party developers consuming your API in the future beyond your own engineering team. Some important points I try to be disciplined about, based on my own experience building APIs in C#, Delphi, Go, Java, Node.js, PHP, Python and Ruby: 1) Document your API from day 1 2) Update your API

I've worked with API Blueprint as it seems to have the widest support across API tooling providers, along with a sane syntax. It's really nice to be able to spec out a blueprint and then simulate an API [1]. Also being able to run tests on the real API, but based on the API docs which describe expected behavior, has exposed many bugs [2]. I just recently watched the "Microservices Summit" from microservices.com/Datawire [3], and the most-repeated lesson from Netflix, Amazon, and Yelp was to design API-first, not data-first. As engineers we tend to design an API around our data -- but developers have to interact primarily with the API, and then with the data. With API spec tools we can quickly fake an API and try to interact with it, then find out what sucks and rewrite it, all before sinking time into the actual implementation. SendG

For dev or CI you might want to take a look at Gavel https://github.com/apiaryio/gavel (or even Dredd for that matter https://github.com/apiaryio/dredd) (disclosure: I work for Apiary.io)

This is kinda neat for being able to show some API workflows (like the PATCH update of a document and then GET request to retrieve it), but if you are more interested / content with one-by-one testing of resources, you can use the API Blueprint project (http://apiblueprint.org) to document your API, and then use Dredd (https://github.com/apiaryio/dredd) to test a running version of your API. You can then tie in with their nice visualization tools or upload to apiary.io and take care of your customer-facing docs while you're at it.