As a developer, I prefer spring restdocs. But as a consumer of the documentation, I find the swagger live documentation to be very compelling. Here's the ubiquitous example: http://petstore.swagger.io/
Is there a way to document my rest apis with spring restdocs but generate live documentation like the swagger petstore with it? If so, how do you do this?
No, it's not possible out of the box. REST Docs is intended to be extensible so you could add the functionality yourself but it would be a significant undertaking.
I'm the lead of the REST Docs project and support for live documentation is of interest, but it's not a particularly high priority at the moment. In my experience, live documentation can be useful as a playground but does a poor job of actually documenting a service. My focus at the moment is on producing accurate and well-structured documentation. Using REST Docs with Slate can give you a big jumpstart on the latter if you're looking for something more guiding than Asciidoctor's blank canvas.
Related
I've been searching for an answer to this problem and found a lot of resources on how to build a REST API that supports pagination, sorting, and filtering, using what are considered best practices by each author. The problem lies in the fact that these best practices seem to be subjective and there isn't a standardized way to implement these features.
The best examples of what I'm looking for are this implementation that makes use of Spring Data and a Gist published by someone who found himself on the same situation. The first solution relies on Spring Data JPA, whereas I'm using vanilla JPA, which would make me change my entire logic. The second example seems a bit crude since the author himself states that it doesn't contemplate HATEOAS and links, which are, from what I've gathered, an important part of a modern pagination for REST APIs.
What I can't seem to find is a "plug-and-play" implementation of these concepts, that can be easily integrated with Jersey, even if it means adapting my JPA logic to use its methods.
Surely there are advantages to custom implementations as they can be adapted to each project's specific needs, but they can lead to some pitfalls and end up hurting the API in the long run. It would be really useful to have some kind of annotation that can be injected and parse all the required fields, such as sort, order, page, etc.
Is there a dependency that I can add to my project that doesn't force me to reinvent the wheel?
I'm currently using this configuration that I adapted from the example provided in the question. It's not optimal but it works until I can find a better solution. Hope this helps someone who's in the same situation!
The application I am developing will be "responsive" , do async communication and pass a lot of JSON back and forth.
I Need a Java MVC WEB framework that supports
1) Minimum amount of BLOAT and "behind the scenes magic". With any framework, there is always a trade-off between framework functionality vs complexity. But, when the time comes when i face a problem and have to "fight the framework"(and that time always comes), I want it to be a fair fight. Minimizing the sheer size of the framework increases the probability of a fair fight.
2) Native RESTFUL support. I.e. route html verbs and perform content negotiation.
3) Straightforward support for processing JSON. Using an arbitrary json processor of my choice, i.e. jackson or gson e.t.c..
4) Straightforward persistance support, e.g. JPA e.t.c.
5) Some set of template systems, e.g. freemarker, velocity e.t.c.
6) Native authentication/authorization security scheme with support for a "role based" security OR Integrate easily with spring security
All of the above should be integrated in the framework. Not in some third party user contributed module that rots away when a new version of the framework comes along.
I sat down for a day and experimented and found the following candidates
Spring MVC 3
1) To get the proverbial "Hello World" example up and running in Spring MVC 3 i needed the following jars:
org.springframework.beans-3.1.0.RELEASE.jar
org.springframework.expression-3.1.0.RELEASE.jar
org.springframework.asm-3.1.0.RELEASE.jar
org.springframework.context-3.1.0.RELEASE.jar
org.springframework.core-3.1.0.RELEASE.jar
org.springframework.web-3.1.0.RELEASE.jar
org.springframework.web.servlet-3.1.0.RELEASE.jar
And finally some definitions in xml file, "dispatcher-servlet.xml". I don't know if that accounts for BLOAT or too much behind the scenes magic. But it doesn't give me a warm and fuzzy feeling of being somehwat in control
2) Spring 3 supports this and from the examples i saw it does not look too nasty
3) Supported, but from the link in (2) it seems as if processing json is limited to using the jackson library. At least if you want to use the magic annotations for content negotation.
Quote:
"Underneath the covers, Spring MVC delegates to a HttpMessageConverter to perform the serialization. In this case, Spring MVC invokes a MappingJacksonHttpMessageConverter built on the Jackson JSON processor. This implementation is enabled automatically when you use the mvc:annotation-driven configuration element with Jackson present in your classpath."
Bit of a warning signal for me. I would like to have clear programmatic control over what JSON processor i am using. Maybe i am missing something here. This qualifies as unwanted "behind the scenes magic" in my book
4) Yep
5) Yep
6) Yes
Play Framework
1) Version 1.2 weighed 88,5 MB on my disk. Doesn't run in servlet container, so getting the hello world example and running was easy peasy compared to spring, where even finding out which jars i needed was shrouded in secrecy. Obviously a lot of stuff happens behind the scenes in play. I guess all I can hope for is that it does not do more than it has to. And that the arcitecture is sane. But, when i have to fight the framework some day, will I be dead on arrival ? Who knows...
2) Yep and it does so elegantly. Thumbs up.
3) Yes, but it uses gson under the covers. Again, why can i not control this programmatically ? Fortunately, one can pass an arbitrary serializer to gson to override the default. And I think that parameter maps to the second parameter of the play renderJSON() native function. So play passes with half a thumb up.
4) Yep. Has a JPA module
5) Yep. Uses groovy. Fine by me.
6) Should be possible by combining the secure and the deadbolt modules. Don't know how well it stacks up against spring security. I dont see any in-built support for password encryption and the likes. And have no idea how difficult (if even possible) it would be to integrate with spring security. Don't know if i would be comfortable deploying sensitive data and relying on the play! framework for security. Would probably have to build something on top of it.
Restlet
Maybe a peculiar candidate as it's marketed to be used for "restless web services". But for my points (1) -(6) and my type of application where most of the user interaction is async, it seems like a good fit. I can run it on static resources or dynamically generated content and spit out any content type.
1) Restlet 1.1.1 is about 54 MB. Glanced the hello world example. I liked the absence of XML files. And just like play it has its own server(jetty connectors). The hello world example looked very clean and easy.
2) Yes, and the approach is very "programmatic"
3) Yes, but it seems only via a jackson extension module. Given the programmatic nature of this framework, it seems likely that there are other options but i didn't find anything in the documentation or in the user group forums.
4) Describes itself as "persistance agnostic". OK, that's good i guess. But i want to persist and not re-invent the plumbing on my own. Or at the very least i want a little howto showing that it CAN be done with some effort. There is a third party jpa module But it's built on restlet 1.0. Restlet has a spring module though, so maybe i can integrate with spring persistance stuff ...
5) Yes, there is a freemarker extension
6) Has a native scheme for this. At a fist glance, not as "rich" as spring security. Again, maybe I can integrate?
SUMMARY
Spring MVC 3: Supports all of the requirements, maybe with the exception of (1). Only concern I have is that it seems complex and I get a vague unpleasant feeling of not being in control. I really don't want to be "bogged down" by the framework later on as my application grows.
Play: Very pleasant experience. Fun even. If only the security scheme was more advanced, or if I could at least integrate with spring security(and find documentation on how to do it)
Restlet: For some reason this framework resonated with me. The Programmatic approach induces a feeling of control. But if I can't do persistance in some easy-cheasy way then it's a no go. Can't really understand why this is not built in. Doesn't everyone need this?
What say people who have used any of the above frameworks?
Are my observations accurate?
Did I leave out a framework that should be here?
Alternatives?
the comparison between Spring and Play is now highly out of date, since Play 2.0 has been rewritten in Scala and is better in almost every possible way.
Check it out: http://www.playframework.org/
I can only speak for Spring here.
When I was forced to use Spring for a non-REST project last year I cringed. Not only did I have just a few days to pick up the basics, I didn't like all the "magic" it did, nor was I familiar with IoC principles.
But it grew on me. It grew on me pretty fast too. Since then, I've used Spring for all kinds of Web projects, including one that exposes a RESTful API.
The strengths of Spring from my perspective are: a) it's actually pretty lightweight and usually keeps out of your way once you've got things configured, b) TONS of examples and a great community for support, c) doing REST is a cinch, once you get your configuration right, d) an API design that makes the gods weep with joy, and e) IoC is life-changing.
Speaking to your concern with bloat... I've used other Web frameworks for Java, and Spring is the least bloaty of them all IMO. It might LOOK like a lot, but it's really not. Compared to Struts and Seam (both of which I still have nightmares about), Spring is antithetical to bloat. Moreover, the IoC will let you get away without having to write tons of boilerplate, making your app less bloaty as well.
You mention you don't want to get bogged down by the framework as your app grows. This will not happen in Spring, I guarantee you. It is designed to stay out of the way and to keep you from becoming dependent on any one framework. Your code--if designed correctly--could drop Spring in the future for something else with not a whole lot of cursing and head banging. It favors convention over configuration, meaning the common stuff should work out of the box without having to tinker around too much. For those things that are off the wall, it gives you enough rope to hang yourself.
In summation, I would highly consider Spring.
The two I can recommend is RESTlet 2.x, which I use on every project. And RESTEasy which I am considering using on an upcoming project.
What I like about RESTlet is all the routing is in one place. It is very feature rich.
What I don't like about RESTEasy, and I have not looked at it all that deeply, is the Annotations have all the routing strewn across the code base on each method, of what could be many classes. Not having them all in one place, will make maintainability more difficult.
Why I am still considering RESTEasy, is having multiple GET methods per class might cut down on the resource class explosion that can occur in RESTlet.
Both are JAX-RS compliant, if that is important, and either one is a solid investment in time and functionality.
As for templating, use StringTemplate, stay away from things like FreeMarker, they just lead to a world of pain in maintainability.
I have looked around a bit on stackoverflow as well as google, but couldn't find any good tool that can document SPRING-REST api. Tried using enunciate, but it barfed out on spring annotations it couldn't recognize. Does anyone know of a good tool for documenting a spring RESTful api ?
Typically you need not document your REST API. Your clients should be provided with the specification of the media type you are using (think Atom or OpenSearch for example) and only rely on the information given there.
As soon as you document anything about a specific service, you are coupling your clients to that documentation (and that service). The result being that your service's ability to evolve is now limited by the amount of out-of-band information the clients have baked in their code (based on your API description).
IOW - when was the last time you needed a service API description to make your feed reader talk to an AtomPub service?
Jan
P.S. The theoretical backgrounds I summarized in [1]. Look specifically at the difference between HTTP Type I/II and REST. And Roy's [2] is a MustRead on this.
[1] http://www.nordsc.com/ext/classification_of_http_based_apis.html
[2] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
Just document everything that needs to be documented from a client developer perspective. And please don't take advice like "you need not document your REST API" seriously. This is a pedantic guidance and not useful in the real world.
Every successful API out there is well documented from client developer point of view. Any API that is hung up on pedantic notions is bound to turn off client developers.
See Chapter 14 of my "RESTful Web Services Cookbook" (http://shop.oreilly.com/product/9780596801694.do) for some examples.
Try using Swagger. It provides few of its own annotation that work well with Spring MVC rest annotations.
I need to write integrations to multiple external web services. Some of them are SOAP (have WSDL), some of them pretty much ad hoc - HTTP(s), authentication either by basic auth or parameters in URL (!), natural-language like XML which does not really map nicely to domain classes..
For now, I've done the spike integrations using Spring Web 3.0 RestTemplate and binding using JAXB2 (Jaxb2Marshaller). Some kind of binding is needed because domain classes need to be cleaner than the XML.
It works, but it kind of feels bad. Obviously this partially just because how the services are built. And one minor issue I have is naming of RestTemplate as services have nothing to do with REST. This I can live with. JAXB2 feels a bit heavy though.
So, I'm looking for some other alternatives. Ideas? I'd like to have a simple solution (so RestTemplate is fine), not too enterprisey..
While some of your services may be schemaless XML, they will still probably have a well-documented API. One of the techniques that the Spring folks seem to be pushing, at least from the web-service server side, is to use XPath/XQuery for retrieving only the information you really need from a request. I know that this may only end up being part of your solution, but I'm not sure that this is a situation where one particular binding framework is going to meet all your needs.
If I understand correctly you have 1 application that has to make calls to various external (web) services by use of different technologies. The first thing that comes to mind is to have some intermediate level. While this could be something as elaborate as en ESB-solution, my guess is that is not what you're looking for.
You could for example achieve this intermediate level by having a class hierarchy with at its top an interface 'Consumer'. Method to be implemented: doConsume() and so on.
If you look into it you'll probably have the opportunity to make use of several design patterns like Strategy or Template. Remember to be pro-active and try to ask a few times 'What if ..' (As in: what if they need me to consume yet another service? etc.)
If JAXB feels too heavy there are other API's to be found:
Axis
JAX-WS
CXF
other
It'll depend on the situation which one would be better. If you run into troubles with any of them I'm sure you'll be able to find help here on SO (and from people who have more hands-on experience with them than me ;-)
Following a merger of two companies, what would be the best tool for enterprise integration:
- Camel or XAware?
- or both for different needs?
It seems that there is some overlap with maybe XAware more focused on data integration and Camel having a wider view of integration (including workflow, routing, etc.)
Your comments?
What are the strengths and weaknesses of each product in such a context?
I would vote for Camel. Though I never used XAware... You can do lot of stuff very easily in Camel and is one of the best frameworks I ever used
Given the lack of more specific information, I'd recommend giving Camel a serious look to see if it meets your needs. It has a strong community following, its open source, has good documentation, is lightweight and flexible (see architecture page for more information).
That being said, I've never used XAware and I am a Camel Committer/IT consultant that uses Camel everyday...