spring rest doc - service layer mocking

Question

recently i saw the blog post say that "for documentation purpose, we use mocking for service layer (in environment using spring rest doc)", so this post use annotation like spring's @MockBean to service layer object.

but i think, if i mock service layer -> spring rest doc always success to test because mocked service object always return intended result and spring rest doc test always receives same intended result from mocked service object.

so i think that is not right but,

i want to know about what is better or how you use service object with spring rest doc

pleas answer

Answer 1

Whether or not it's a good idea to mock the service layer when using Spring REST Docs is largely down to personal preference.

A possible disadvantage of mocking the service layer is that it may be possible for the documentation to get out of sync with the service's actual behaviour. This undermines REST Docs' ability to help you to keep your documentation and service in sync.

An advantage of mocking the service layer is that it can make it easier to document error scenarios or scenarios that would otherwise require quite a lot of setup. In the case of errors, I think you are better adopting a common approach across your whole API and making consistent use of standard HTTP error codes. If you do this, the need to document error responses for each endpoint in a service is reduced.

This leaves documenting more complex scenarios that require a lot of setup. In this case, limited use of mocks may be worthwhile but I would still aim to produce as much of your documentation as possible without relying on mocks.