We&#x27;ve tried various ad-hoc approaches to documenting our APIs in the past.<p>When we switched to RAML (and json schema) for our API definitions, everything got a lot better.<p>RAML defines the resources (uris, parameters, media types, etc.) while json schema is used for more detailed information (what&#x27;s the exact structure of the application&#x2F;json response to a call to GET &#x2F;jobs).<p>While there are theoretical gains in generating code from the RAML, we don&#x27;t seek these out as its no big deal to hand-code Spring controllers, even a lot of them.<p>The real value for us is in having a single, well-documented  source of truth about our APIs. Customers using the APIs, developers implementing them, testers testing them, trainers learning about them, all go to one place.<p>And RAML has some handy tools (like raml2html) to create human-readable documentation from the RAML.<p>We&#x27;ve also added our own tools to parse sample json responses against the json schema which have greatly aided us in finding discrepancies.<p>In short something like RAML (or probably blueprint or swagger too) is, I feel, essential if you have a lot of APIs and a lot of people, and if you have aspirations of an increasingly automated toolchain.<p>FWIW, there&#x27;s a line of thought that RAML is at odds with hypermedia and HATEOAS. After all, why would anyone need a detailed API document, when clients should be getting information from the hypermedia responses of previous API calls? I don&#x27;t agree with that, even if just because internally your development team still needs to build out all those APIs.