Should I mix integration testing and rest documentation with Spring Boot?

Question

Spring Rest Documentation (spring-restdocs) is a very good replacement for Swagger when working with Spring Boot. Is it better to mix integration tests with Rest documentation tests or to create separate Rest documentation tests even if some tests are duplicated?

Answer 1

I won't be surprised if this is closed as being primarily opinion-based. That said, I think a case can be made for keeping things separate.

The tests used for documentation and your other tests are quite different in nature. Generally speaking, you will only be interested in documenting the golden path through your API and won't want to generate documentation for (many) errors or for handling extreme input.

Keeping the tests separate helps to reinforce this difference in purpose and makes it easier to quickly determine what a test is supposed to be doing: documenting the API or verifying its functionality.