Treat documentation as first class folks. DOCUMENTATION is important. And yes, code does does replace a good documentation. Code and documentation are not mutually exclusive.

For a while we have been using JSON schemas to document our API endpoints. Those schemas are used to validate input and functional / accaptance tests use the JSON schemas to validate the the output of every endpoint. And the examples in the JSON schemas are validated against the schema itself, to make sure the documentation itself is correct as well.

The end result is that our documentation always matches the input/output from our endpoints and that all the examples in the documentation are treated at valid input/output.

I would really recommend this workflow for documenting API endpoints.

"code does does replace a good documentation"
I do not agree with that completely. Code does only replace the documentation for how you do something, but it does not replace that explains why you do it in a certain way.

Agree with it, I meant Code does not replace the documentation, could not edit the original rant

I love to document my stuff, it infuriates me that people write code, are even passionate about it, but can't be bothered to document it, so others can use it.
That's just selfish.