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).
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 docs every time you commit a new change to your models/controllers/endpoints
3) Test your API docs against your actual implementation. Dredd is a great tool for that: https://github.com/apiaryio/dredd
4) Build an API client from day one (web app, command line app, desktop app, whatever), and use it for testing the consumption of your API endpoints, and update it every time your API changes
* Benefits: you're gonna have a perception of the developer experience that your API users are going to have when consuming it, and very likely that will bring you some insights on opportunities to make things simpler or better documented (header params, query params, request payloads, endpoints signature, response status codes, ...)
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. SendGrid does this, and their API has been a breeze to work with [4].
The last step is to use a client SDK generator like Apimatic [5] -- but that only works if the API actually conforms to the docs. It's probably difficult to get an entrenched codebase to switch to spec, but for any new API I wouldn't do it any other way.
[1]: https://github.com/localmed/api-mock or https://apiary.io
[2]: https://github.com/apiaryio/dredd
[3]: https://www.datawire.io/microservices-practitioner-summit-wr...
[4]: https://sendgrid.com/blog/quickly-prototype-apis-apiary/
[5]: https://apimatic.io
(disclosure: I work for Apiary.io)