I am trying to build microservices with design first approach and using akka-http(scala) 2.4.1. For the design-first, IMHO, swagger is widely used. I couldn't find any boilerplate implementation as to how swagger works with akka-http.
How could I proceed?
I found a thread https://github.com/akka/akka/issues/16591 which talks about this to some extent, but couldn't find a conclusion / approach to take.
Also, there seems to be one not maintained version of a library https://github.com/Tecsisa/akka-http-swagger
In the swagger community, found a thread indicating to use swagger-inflector for ensuring the implementation is adhering to the swagger spec developed, but that seems to blend well with java and not with scala.
Related
I like the TDD approach to documenting your restful api with spring-rest-docs. However, I love "API Playground" feature enabled by swagger specification. I wish there was a way to get best of both worlds.
Is there a way to build swagger2 specs from spring rest docs? may be via building custom request/response preprocessors.
Do you have any thoughts or recommendations?
There's not out-of-the-box support for this in Spring REST Docs at the moment. The issue that you opened will track the possibility of adding such functionality. In the meantime, your best bet would be to look at writing a custom Snippet implementation that generates (part of) a Swagger specification.
Typically, a Spring REST Docs snippet deals with documentating a single resource, whereas a Swagger specification describes an entire service. This means that the Swagger specification Snippet implementation will need to accumulate state somehow, before producing a complete specification at the end. There are lots of ways to do that (in memory, multiple files that are combined in a post-processing step, etc.). It's not clear to me that one approach is obviously the right one so some experimentation would be useful. If you do some experimentation, please comment on the issue that you opened with your findings.
I've been trying to find a simple all purpose unit test framework for Spring MVC based Rest Services I've written.
I've been searching online and narrowed it down to:
RestFuse (http://developer.eclipsesource.com/restfuse/)
Rest Assured (https://github.com/jayway/rest-assured)
MockMVC (http://www.petrikainulainen.net/programming/spring-framework/unit-testing-of-spring-mvc-controllers-rest-api/)
I like RestFuse because it's mostly annotation based, but rest assured seems to have a easier way of passing parameters and checking responses. And finally being a Spring MVC Rest Service project, I'm wondering if I should just stick with the already established way of testing Rest Services in Spring with MockMVC.
Interested to get any feedback, as well as performance, past experiences and if there's anything else I should take into consideration.
Rest-Assured is gaining acceptance over the other frameworks to test REST services in Java. Having BDD style fluent interface, its easy to read the test scripts also, with minimal learning curve.
I am using this framework for verifying REST services as an end user, and it has been easier to implement test scripts for them. Hence I cannot comment much on Spring MVC part of REST-assured.
However, this blog post gives you more details on RestAssured v2.2 which includes spring-mock-mvc module built on top of MockMVC giving BDD style fluent interface flavor through REST assured. The blog post also cautions:
When not to use it:
RestAssuredMockMvc is not to be considered a complete replacement to
vanilla MockMvc since it contains more specific features coupled to
Spring MVC. For example right now there’s no first class support for
things like flash attributes and principals. You can how ever add
those by using an interceptor. Standard REST Assured also supports a
lot of different authentication schemes and filters which are not
available in the RestAssuredMockMvc API. Another reason for why you
may want to use the standard REST Assured API is if it’s important to
your organization to test the REST API in a real container (for
example if you’ve configured authentication or authorization in a
container specific manner) or if you’re using JAX-RS (or any other
framework regardless of language).
Finally, have a look at REST-Assured spring-mvc-webapp examples in REST-assured codebase, and decide, whether you like to give a try for it and make the best use of both REST-assured and MockMVC frameworks.
The beauty of MockMVC is that it provides a mock servlet container, allowing you to integration-test your REST services without deploying to a web server. I believe that you can still leverage this power when using REST Assured with the spring-mock-mvc module.
Another framework that I just learned of is Karate. Its author is currently experimenting with a mechanism to allow execution in a mock servlet container (see Peter Thomas' answer to Is there a mechanism for integration testing JAX-RS services without deploying (a la MockMVC)?).
Spring REST Docs was released recently and the documentation says:
This approach frees you from the limitations imposed by tools like Swagger
So, I wanted to ask when Spring REST Docs is preferable to use comparing to Swagger and which limitations it frees.
I just saw a presentation here that touches on your question among other topics:
https://www.youtube.com/watch?v=k5ncCJBarRI&t=26m58s
Swagger doesn't support hypermedia at all / it's URI centric
Swagger's method of inspecting your code can lag behind your code. It's possible make a change in your code that Swagger fails to understand and won't process properly until Swagger gets updated.
Swagger requires lot of annotation, and it's painful to include the descriptive text you want in an api document in annotations.
There are just some things that Swagger can't figure out from inspecting your code.
In any case, these are just a couple of points. The presenter does a much better job discussing it than I could.
I thought I would chime in to give a little bit more context surrounding Swagger, what it is, and what it is not. I believe this might help answer your question.
Swagger 2.0 is being adopted by a lot of big names and big platforms like Microsoft Azure, Paypal, SwaggerHub.com, DynamicApis.com, etc... Something to keep in mind is that Swagger is very simply a specification. It is not a framework. There are a lot of frameworks out there built to generate Swagger output that crawl through your code looking at your API information in order to build the Swagger 2.0 JSON file that represents your API. The Swagger UI that you see your APIs on is driven directly from this Swagger 2.0 JSON file. fiddler it to check it out
It is important to note that a framework that was created to allow you to "use swagger" is not how Swagger has to work (i.e. it is completely up to the implementation of the 3rd party framework). If the framework you are using to generate your Swagger 2.0 documents and UI is not working for you then you should be able to go find another framework that generates the Swagger artifacts and swap the technologies out.
Hope this helps.
From Spring REST docs:
The aim of Spring REST Docs is to help you to produce documentation for your RESTful services that is accurate and readable
This test-driven approach helps to guarantee the accuracy of your service’s documentation. If a snippet is incorrect the test that produces it will fail.
Spring REST docs advantages:
Documentation is written in the test code so it does not overload main code with lots of annotations and descriptions
Generated docs and examples are accurate because related test must pass
Docs can provide more specific and descriptive snippets
Format is suitable for publishing
Spring REST docs disadvantages:
Requires more work
Documentation provides request/response examples but don't provide interactive tools to modify and try out requests
Swagger advantages:
Quick, automated generation from a code
Interactive request execution - can be used for acceptance testing
Built around the OpenAPI Specification
Swagger disadvantages:
For more descriptive documentation it will require a lot of annotations
Tests are not related to the documentation so sometimes documention may deviate from reality
There is some limitation with swagger and the specific spring stack.
For example : with "param" in your Request Mapping you can define more than one method with the same url ans so simplify your code.
But swagger show you just one method
One disadvantage with Swagger is: it cannot handle models which have cyclical dependencies. If a model has cyclical dependency and if swagger is enabled, then spring boot server crashes.
We are about to take on a large project implemented in Grails (2.3.7). The application makes heavy use of many different (end-points as well) REST-ful webservices. We are of course interested in using what is considered to be "best standards" (at least currently).
We are currently considering:
- Using the Groovy HTTP-builder
- Using the "REST Client builder" plugin
Any other we should consider and what are your experiences using the above mentioned?
I have used both http://grails.org/plugin/rest and http://grails.org/plugin/rest-client-builder and both provide a nice wrapper around HTTP Builder library. The "rest" plugin provides dynamic methods for you if you like using that syntax. I prefer REST client builder though. Both are easy to work with.
For example, Play-framework supports RESTful services like this: RESTful on Play! framework
How does this compare to something like Jax-RS Jersey implementation? Does a framework like Play run circles around Jersey because of all it's cool bells and whistles, and it does REST too?
Developer productivity is important, but so is a proper implementation. Perhaps using an MVC framework for REST only services is 'wrong'?
Note, only RESTful services, no UI components at all.
Even though it's not "wrong" to use an MVC framework for RESTful services, there are some pros and cons versus using a JAX-RS implementation.
(Disclaimer: I have only used Jersey and Play! for fun, and not on production-grade systems, so I have tailored my comments more generally to MVC vs. JAX-RS. Keep in mind that these are broad generalizations.)
MVC frameworks--at least the ones that are considered developer friendly and "slick"--typically save you from having to build a persistence layer (the model part). Most also simplify "routing" requests using either scaffolding via convention or some form of configuration. The downsides are that you have to conform to some conventions for your controllers and usually have to write a view for each resource (or build layers of abstractions to avoid rewriting the same code).
JAX-RS excels at defining the routing (using Java annotations) as well as eliminating any restrictions on the service class. In my experience, that has greatly reduced the amount of boilerplate code and developer overhead. Jersey and Apache CXF also handle the XML or JSON serialization using JAXB annotations, which eliminates the need to figure out the view in an MVC context. The downside here is that you have to figure out your own ORM or persistence layer, which could be good or bad depending on whether you're building on top of existing data or creating a greenfield system (or using something other than an JPA/RDBMS e.g. NoSQL data store).
My own personal comment: Play! is a really cool framework, but I'd choose CXF (or Jersey) over an MVC framework any day for building out a RESTful service. In my experience, this frees up the developer to focus on the logic needed for the service, and opens up options for different database approaches. Right tool for the right job.
As a rule of thumb: For Scala, use Play. For Java, use Jersey.
You can use Jersey/Scala and Play/Java; I've done both. It works. It isn't bad. But unless you have a particular reason to do that, I wouldn't mix ecosystems. Java and Scala are interoperable but they have different ecosystems, I would avoid adding Java-isms if you are using Scala or Scala-isms and dependencies if you are running straight Java.
Jersey and Play are generally close for REST services. Neither really has any killer features over the other.
Jersey defines URL mappings in annotations, Play defines them in a service wide route file. And they bundle or have varying quality of integration with different libraries for things like XML, JSON, database, testing, mocking, dependency injection libraries and app server deployment.
The Java world has JMS, Spring, JUnit, jdbi/hibernate/jpa, Jetty/Grizzly. The Scala world has Akka, specs2/ScalaTest, Anorm/slick. Jersey is a better fit for the first world, Scala for the second. You can definitely cross that, but it will be a little less elegant and might require more glue coding.
JAX-RS is a standard and implementations can be created by different vendors. Jersey is one such implementation. The other frameworks may make use of JAX-RS but are not standards. So it is not a one-to-one comparison.
I have never heard of Play before but it does look interesting, more akin to Rails and Django than Jersey. What I like about Jersey is that it can be integrated into existing Java web applications by simply adding the JARs and declaring some things in the web.xml. What I find confusing about Jersey and JAX-RS is the routing.
Play seems to make routing easier, however, correct me if I'm wrong, seems like it is an all-or-nothing framework and cannot be used alongside other servlets in the same web application.