I didn't find the way how to describe all my response codes, and I see only default ones. I have a lot of responses, and want to describe them. Also I'm interested in describing different requests which cause 400 response error(for example that request with such kind of data will return that message and so on), should it be described in API documentation?
Apigility works seamlessly together with ZF Api Problem for error handling.
Creating an error response from a controller or listener is as simple as:
use ZF\ApiProblem\ApiProblem;
...
return new ApiProblem(500, "My Internal Server Error");
The status titles for common errors are set here in the class.
It is advisable to stick to valid http error codes that suit the problem that occurs, but you can of course customize the title. You can return your ApiProblem directly from your controllers and listeners, Apigility will properly handle the error and return a rendered json response with Content-Type headers set to application/problem+json.