Should Internal Server Error be documented in swagger?

Question

I am writing a new API and documenting it using Swagger/OpenAPI. It seems to be a good standard to document error responses, that the developer can expect to encounter. But I cannot find any guide lines or best practices about Internal Server Error. Every path could in theory throw an unhandled exception. I do not expect it to happen, but it might. Should all paths have a response with status code 500 "Internal Server Error" or should I only document responses the developer can do anything about, i.e. 2xx, 3xx and 4xx?

Answer 1

The offical documentation shows an example for specifying all 5xx status codes in the responses section, but it does not go into details about the specific status code, or the message returned. It also mentions that the API specification should only contain known errors:

Note that an API specification does not necessarily need to cover all possible HTTP response codes, since they may not be known in advance. However, it is expected to cover successful responses and any known errors. By “known errors” we mean, for example, a 404 Not Found response for an operation that returns a resource by ID, or a 400 Bad Request response in case of invalid operation parameters.

You could follow the same approach and specify it like in the example. I think it's not important or even recommended to try to describe it more specifically, since you might not be able to cover all cases anyway and the client is not expected to act on the message returned for internal server errors (possibly other than retrying later). So for example, I would not recommend specifying a message format for it.

Omitting any responses with 5xx HTTP error codes makes sense as well.