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
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.
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.
Related
The idea behind HATEOAS is actually very simple, that is, in response to a link containing other resources that the client can use to interact with the server, the client cannot know that the server workflow, but can know the next steps in the resource link from the root links, but only the link, not Request parameters and examples This is a far cry from the online documentation generated by Swagger2 (personal feeling)
On the other hand, when it comes to code writing, looking at Spring Hateoas or using Spring ApplicationListener is hard-coded, it feels very cumbersome and feels like no swagger2 annotations are easy to use.
This problem bothers me, I don't know if my API should use the Hatepas way
Spring Data REST creates a CRUD web server with a discoverable API, so it seems it should be possible to write a generalized web client application for it. Is there such an application?
May be you are looking for a HAL browser
https://www.baeldung.com/spring-rest-hal
or
something like https://www.npmjs.com/package/angular-spring-data-rest
https://www.npmjs.com/package/angular4-hal
I hope you mean sample client stubs. Actually a web client cannot be generalized beyond the resources it has. That will not be quite meaningful.
You can try below with swagger. Using swagger here would be really convenient (over raml etc) since spring-data-rest generates swagger it self for you.
Take your swagger spec
Paste it at https://editor.swagger.io/.
Go Generate Client => Your favorite programming language.
Then it will generate sample client stubs for you in the language you have selected.
I think this should be the far most generalized point that makes sense.
-Addition-
The primary problem spring-data-rest has solved is abstracting out all the common functionalities attached to controller (ex: response/request mapping etc) and making them readily available and configurable, so that the developer no longer needs to re-invent/duplicate them every time when they are coding a new endpoint.
So as you have suggested generating client-stubs is completely out of spring-data-rest scope. Please read the documentation for more info.
Does anyone know of a link to a useful documentation on how to add swagger documentation to an existing aws lambda (API Gateway)? Some sort of a noob tutorial as I am totally new to swagger.
I have found some links, such as the following, which were not so useful or not specific to lambda:
https://blog.cloudboost.io/adding-swagger-to-existing-node-js-project-92a6624b855b
https://github.com/swagger-api/swagger-node
I have only used Swagger with API Gateway with the old v0.5 version of serverless framework as there was a plugin that supported this easily.
However, when serverless matured into v1.0 and up, at that time, there were no good plugins for Swagger integration.
Here are links you can check:
Serverless Github Issue: Swagger Integration
Reckon-Limited/serverless_swagger
doapp-ryanp/serverless-plugin-swag
I don't personally use the above though as my big serverless projects are now using GraphQL (where API documentation is part of the standard tooling :-) instead of REST.
In my backend team we do the documentation using a tool that smart bear makes available, the swagger inspector and through it we finish adjusting the doc with the swagger hub.
Swagger inspector makes a request on your endpoint and basically extracts the necessary documentation, but some things you need to adjust, it is not the best solution, but it helps ...
im currently thinking how to build REST API docs for my application with support for multiple languages. Endpoints, parameter names and return values should stay the same but the description of each REST method i want to provide in different supported languages.
Im using Spring boot, data & rest and found this docs project what seems very useful to me. Anyway, i couldn't find any informations in the docs regards the i18n topic/support.
Does anybody know if Spring REST docs support the generation of the API doc for multiple languages (in general)?
REST Docs doesn't provide any out-of-the-box support for I18N but it should be pretty straightforward to build something on top.
The main piece with which REST Docs is involved and that I think you'd want to translate are the descriptions that are included in the various snippets. Rather than hard-coding a particular description, you could look each up in a ResourceBundle:
ResourceBundle resourceBundle = ResourceBundle.getBundle("field-descriptions");
mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON))
.andExpect(status().isOk())
.andDo(document("example", responseFields(
fieldWithPath("a").description(resourceBundle.getString("a")),
fieldWithPath("a.b").description(resourceBundle.getString("a.b")))));
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.
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.
This project generates an OpenAPI specification from Spring REST Docs.
https://github.com/ePages-de/restdocs-api-spec