Including a “try out” form in Spring REST Docs

Question

I am starting to use Spring REST Docs but I miss a nice feature of swagger... the "try it out!" button that includes a HTML form to test the API. I get the curl link OK; but I usually use swagger form. Is there a simple way to do this in Spring REST Docs? Thanks

Answer 1

I solved it for myself by creating a tool to convert Spring REST Docs cURL snippets to Postman collections. It's available as a npm package: https://www.npmjs.com/package/restdocs-to-postman that can be used on the command line and as a library. This is one solution for https://github.com/spring-projects/spring-restdocs/issues/47 . In my opinion tools like Postman are good to try out APIs.

Edit: There are converters from Postman and Insomnia to Swagger. So with two conversions (restdocs to Postman/Insomnia and Postman/Insomnia to Swagger) one can get a Swagger playground. This is not optimal, but works.

Examples for converters:

• Postman to Swagger: https://apimatic.io/ (paid service with trial)
• Insomnia to Swagger: https://github.com/mlabouardy/swaggymnia (MIT license)

Edit 2: I have created instruction on how to create a Swagger playground out of Spring REST Docs: https://github.com/fbenz/restdocs-to-swagger It takes a few steps and would be simpler if Spring REST Docs would directly produce a Swagger file, but it works and can be automated.

Answer 2

No, the closest I believe it can provide is a curl with an example request. There is an open enhancements to provide Postman collections, https://github.com/spring-projects/spring-restdocs/issues/47 , but nothing as simple as Swagger's try it out!

Also somewhat related from this ticket, https://github.com/spring-projects/spring-restdocs/issues/213 ,

I'm rather torn on trying to add support for generating a Swagger specification. When you describe Swagger as providing an "API Playground", you've drawn a very important distinction that many others do not. I firmly believe that Swagger's UI is not a substitute for API documentation and using it as such isn't good for a service or its users.

My fear is that if Spring REST Docs provided support for producing a Swagger specification, people would then use that specification to populate Swagger's UI and consider their service to be documented. It's a matter of weighing up trusting people to do the right thing, versus encouraging people to shoot themselves in the foot.