1

I have seen this Spring REST Docs - video

We are doing Spring boot projects and are using springfox library for generating the Swagger-ui and swagger documentation as outlined here

We like what Spring Rest docs can do for generating REST API documentation and the fact that we don't have to add swagger annotations like @ApiResponse or @ApiOperation in our Controller code. And also the fact that the documentation now lives with the code.

But if go with Spring Rest docs, we will miss out on the Swagger-UI that gets automatically generated for our API (when we use swagger integration).

Is it possible for Spring REST docs to generate a test UI like Swagger UI.

2 Answers 2

1

That pretty directly goes against the design idea and intention of Spring REST Docs. One of the main goals of it is that the docs are tied to unit tests so you know your documentation is rock solid even when you make logic or signature changes in your REST contract.

Also as the video you linked to provided a number of examples of how automated docs generation produces a lot of undesirable un-intended output.

So its a choice of do more work to get much better docs, or do the fully automated option to save time and get workable, but lower quality docs. It is what ever your priority is.

2
  • 1
    If swagger specification was generated by Spring REST Docs itself, I don't see why it would go against the Spring REST Docs intention. If the test fails, no documentation nor swagger specification nor swagger ui would be generated. Aug 23, 2017 at 8:41
  • Not the regular unit tests, the specific tests you have to write for the RestDocsAPI. That is how you configure SpringRestDocs is having a specific set of tests that have an entery for every field. If one if a field(s) change and that is not reflected in the deticated Spring RestDocs test it will stop the build because your docs are no longer in sync with your REST contract.
    – BrianC
    May 8, 2020 at 16:24
1

This project generates an OpenAPI specification from Spring REST Docs.

https://github.com/ePages-de/restdocs-api-spec

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.