CODEWITHSUNDEEP
springspring-restdocs
user1167313
user1167313

Reputation: 61

Spring REST Docs interrogating @RestController?

I'm looking at Spring REST Docs and wondering if it has the ability to interrogate @RestController methods to produce basic documentation describing a Rest API (methods, http method, parameters, response type)? I believe Springfox Spring/Swagger does that, and would be easier than having to write a test to get that basic info/documentation.

Also, since I don't want to run integration tests in a Production environment, is the Spring RestDocs approach to run your integration tests in a Test environment and then copy the generated docs/snippets into the war so it can be viewed in a Prod environment?

Upvotes: 1

Views: 349

Answers (2)

Andy Wilkinson
Andy Wilkinson

Reputation: 116281

I'm looking at Spring REST Docs and wondering if it has the ability to interrogate @RestController methods to produce basic documentation describing a Rest API

Spring REST Docs is test-driven and deliberately doesn't take the approach of introspecting @RestController methods. You REST API documentation is describing HTTP requests and responses. By being test-driven and working with real or mocked HTTP requests and responses, REST Docs ensures that what you're documenting is what users of your API will be dealing with.

The problem with introspecting @RestController methods is that it's only one small piece of the puzzle. When an HTTP request is received it passes through filters, interceptors, HTTP message conversion etc before it reaches your controller. The same is true in reverse when a response is being sent. Without a complete understanding of everything that happens before your controller's called and everything that happens after your controller returns, the documentation is at risk of being inaccurate.

is the Spring RestDocs approach to run your integration tests in a Test environment and then copy the generated docs/snippets into the war so it can be viewed in a Prod environment

Correct. The documentation is generated once at build time and then typically served as static files from your application. Details of how to do this with Spring Boot are included in the documentation.

This approach has the advantage that none of the code that's involved in creating the documentation is running in production. That reduces your application's footprint, and avoids the possibility of the code that's generating the documentation from causing a problem in production. I believe you can take a similar approach with code-first Swagger tools but, in my experience, it's unusual for people to do so.

Upvotes: 3

Sergii Getman
Sergii Getman

Reputation: 4381

Swagger is best choice for me. You cannot do make docs with Spring Rest Docs without integration tests. It's good article reviews rest tools

Upvotes: 0

Related Questions