We've tried various ad-hoc approaches to documenting our APIs in the past.
When we switched to RAML (and json schema) for our API definitions, everything got a lot better.
RAML defines the resources (uris, parameters, media types, etc.) while json schema is used for more detailed information (what's the exact structure of the application/json response to a call to GET /jobs).
While there are theoretical gains in generating code from the RAML, we don't seek these out as its no big deal to hand-code Spring controllers, even a lot of them.
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.
And RAML has some handy tools (like raml2html) to create human-readable documentation from the RAML.
We've also added our own tools to parse sample json responses against the json schema which have greatly aided us in finding discrepancies.
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.
FWIW, there'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't agree with that, even if just because internally your development team still needs to build out all those APIs.
When we switched to RAML (and json schema) for our API definitions, everything got a lot better.
RAML defines the resources (uris, parameters, media types, etc.) while json schema is used for more detailed information (what's the exact structure of the application/json response to a call to GET /jobs).
While there are theoretical gains in generating code from the RAML, we don't seek these out as its no big deal to hand-code Spring controllers, even a lot of them.
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.
And RAML has some handy tools (like raml2html) to create human-readable documentation from the RAML.
We've also added our own tools to parse sample json responses against the json schema which have greatly aided us in finding discrepancies.
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.
FWIW, there'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't agree with that, even if just because internally your development team still needs to build out all those APIs.