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.
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
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.
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?
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.
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
This Guide shows how to easily create a RESTful interface to a Mongo Database. It produces Json-data in HAL format(Hypertext Application Language), but unfortunately I am unable to find a working Android Client that supports HAL.
Is there any way to disable this HAL format an just GET the documents from the DB without any extra? So that it can be directly parsed into my datatype classes?
It would be really nice to use this approach to somehow automatically generate the REST interface, I cannot go back to manually writing all the methods in controllers after seeing this very short code.
This post seems to deal with the same topic, but I do not understand how to do this configuration.
The guide you are linking to is specifically aimed at using Spring Data REST + Spring Data MongoDB, so to disable the hypermedia for a project designed to generate hypermedia, i.e. a RESTful interface, sounds very strange.
On a mobile platform like Android, the question is what are you trying to do? Are you trying to query for a single, small piece of JSON from MongoDB? The risk of not having any type of hypermedia layer in the middle is that you could query for a giant (i.e. humongous data set) and cripple both the server and mobile device.
For more details about hypermedia and Spring Data REST, check out Oliver Gierke's answer at Disable Hypertext Application Language (HAL) in JSON?.
Regarding the ability to communicate between Android and a HAL backend, of course it's possible. You may wish to look at Roy Clarkson's sample Android app used to talk to a HAL backend that was used at SpringOne 2014 at https://github.com/SpringOne2GX-2014/spring-a-gram-android.
The slides from that presentations are at https://speakerdeck.com/gregturn/springone2gx-2014-spring-data-rest-data-meets-hypermedia.
I have a design problem at hand. Traditionally I had been developing Spring MVC/Struts/jsf applications with either REST/SOAP service serving the data.
Now we have HTML5 and other javascript frameworks. In this light, do we still need to create Spring MVC applicationS as such (assume that the data is served from a RESTful service)
If I go ahead with pure HTML5, CSS UI (with Ajax calls to RESTful services), what are the possible issues that I may get into? does this approach have security holes like being prone to cross site scripting?
Is it a good approach to start off with? Would this approach be called a single page app?
You still need to serve your single page app from somewhere, along w images and css files. This could be a Spring MVC servlet, or whatever.
I'd look into Spring Data REST which is a servlet that creates RESTful HATEOAS endpoints for you.
It's probably easier if your SPA and REST service are on the same domain, so you don't have to worry about cross-domain restrictions.
They are still vulnerable to XSS, as is any system unless you take counter-measures. Spring security can help here. Make sure you follow the OWASP guidelines.
Use Hibernate Validator's #SafeHTML annotation to prevent unsafe HTML input into your database. Use Spring Security's <content-type-options/> , <xss-protection/> , and <header name="Content-Security-Policy" value="..."/> settings to help fight XSS.
Spring MVC, Struts, etc. provide two core functions: Routing, and Binding.
Routing is dispatching an HTTP request to the relevant piece of code.
Binding is converting the world of Strings that the HTTP request sends you in to something more useful, such as a generic Java bean with not just Strings, but integers and dates.
Along for the ride are aspects such as validation.
Finally, they provide an environment that's particularly friendly to your view layer.
None of these aspects, per se, are obsolete in a world where all you have is JSON coming up and JSON heading back. You still need routing, but now you may care to route not simply on the request url itself, but on HTTP verb. You still need binding, having the framework marshal the JSON payload into some easier for java to work with is very handy.
But, (and I speak in general terms, not specifics as I don't know Spring or Struts well at all), while the MVC frameworks can fill the role of a backend system for a more JSON oriented and raw HTTP world, the specific REST frameworks do the job better.
There's no mistake that the MVC frameworks were a significant step up over raw Servlets. Raw Servlets are functional, but simply too primitive for real work. But with design decisions made from a world 10 years ago, some parts show their age and get in the way in the new world of more raw HTTP requests.
If you're doing a mixed app, some MVC, and some HTTP/Ajax methods, then it's better to work with your MVC framework than adopt a new one.
If you're doing a pure singe page app, then it's worth your while to adopt a framework that tends to that niche. They'll simply be a better fit.
Mind, also, they can live side by side. You can have both co-habitate in a single WAR if you wish, particularly if you're adding SPA features to a legacy application. It doesn't have to be an either/or situation.
But I wouldn't introduce an entire new infrastructure component simply to handle a couple of ajax calls. In the end, they're just HTTP calls, and the MVC frameworks (in contrast to most component frameworks) do just fine with raw HTTP for the most part.