Document response status with Spring REST Docs

Question

I'm currently using Spring REST Docs to generate documentation for my RESTful service, and I want to generate a table of possible values of response status with descriptions, like it's done here(in the bottom of the page).

I can do it manually in my parent index.adoc file, which includes generated ones, but I don't like it since it makes my documentation spilled apart although I want to keep the whole signature description in a single place.

I've read REST Docs documentation and searched it on StackOverflow and the project's GitHub issues, but haven't seen any mention of such a feature.

Am I missing something, or the feature I'm looking for is not implemented and is not even needed?

Answer 1

The feature you're looking for is not implemented and, in my opinion, it isn't needed.

When you're developing and documentation a RESTful API, you should try to make your API as consistent as possible in how it uses HTTP status codes and you should also use the standard, well-understood meanings of each status. If you follow these two guidelines you can either avoid documenting the status code altogether, or you can document them once in an overview section.

The documentation you've linked to provides a few examples of what I don't think you should do:

1. It documents that a 200 means the request was successful. That's the standard meaning of a 200 response so the documentation adds very little
2. 402 is used for a blocked API key but it actually means Payment Required. A 403 (Forbidden) response may have been more appropriate
3. It abuses 404 (Not Found) to indicate that a rate limit has been exceeded

In short, making non-standard use of HTTP status codes has meant that they need to be documented. If the non-standard use varies from resource to resource, then it's also meant that they need to be documented for every resource.

If you avoid making the mistakes described above you can save yourself some work and make things easier for your users at the same time.