Enterprise Integration Zone is brought to you in partnership with:

Lieven Doclo is a Belgian consultant specialized in Java development. He's currently working for a Java-centric consultancy firm. He's an avid OSS supporter and has an healthy appetite for new and disruptive technologies. Lieven is a DZone MVB and is not an employee of DZone and has posted 26 posts at DZone. You can read more from them at their website. View Full User Profile

Swagger Is Great, But...

08.29.2014
| 8553 views |
  • submit to reddit

Nobody likes to write documentation. However, in the REST age where REST-based webservices are ubiquitous, documentation for public webservices is a necessity. There are a lot of tools out there that provide REST documentation generation, but there’s one that stands above the rest (pun intended): Swagger. Swagger is a JSON format that describes a REST webservice. However, the strength of Swagger is the UI, which is a JavaScript HTML5 UI that is just awesome.

Even better, the integration with Spring MVC is top notch. Configuring Swagger in a Spring Boot application is as simple as adding a dependency and adding an annotation (hint for the Swagger guys: provide an autoconfiguration for Spring Boot).

That being said, there are some things that really, really annoy me. See, Swagger is built using Scala. Which also means that if you want to use Swagger, you’ll be pulling the entire Scala runtime into your build. For a Spring Boot application just serving a basic Spring MVC REST service, this means the build goes from 15 Mb to 48 Mb. Urgh. Tripling my build size just to add documentation is enough for me to call it a day and throw it out of my build.

Another thing is that Swagger really doesn’t work in a microservices environment, at least not with Spring MVC. Swagger needs to be in the build with the REST controller, so this means you’ll be including Swagger into each and every microservice deployment (dragging the 33 Mb overhead everywhere you go) and you’ll have multiple Swagger JSON files. Double urgh. I have yet to find an aggregator that merges different Swagger JSON’s into a single one.

Of the 2 issues I have with Swagger, the size issue is the one I find the most annoying. I understand that it’s cool to use Scala but if using a library would mean my build grows 3 times in size I would think twice of using it, especially if it’s just for generating documentation. I personally think Swagger should be lean and mean. Just cutting Scala from the library would reduce the overhead by 20 Mb (I use Groovy rigorously and even then I don’t like the fact that it adds between 4 and 8 Mb to my build). But it’s also just POM sloppiness: pulling in mockito (should be a test library), 2 versions of cglib, JodaTime libraries (which for Java 8 users might not be desirable), … Some proper POM maintenance seems to be in order.

And as for the JSON aggregation, I don’t think it would take me too long to write something in JSON that reads the different JSON’s and aggregates them into a single one (which would also solve the nagging CORS issues you’d be having otherwise). Come to think of it, it would be great to make an aggregator to which applications can push their Swagger JSONs on startup. That way you would have some sort of automatic aggregated documentation that updates itself after each deployment and to which adding a microservice would be a breeze. Documentation as a service, I like it. Another day, another post, another idea.

Published at DZone with permission of Lieven Doclo, author and DZone MVB. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

Claus Ibsen replied on Fri, 2014/08/29 - 1:44am

Yes I agree. 

For starters I would love a pure swagger java api of their model and annotation classes. So I can build a swagger model without any Scala runtime dependencies. We do this in Apache Camel where we allow end users to define REST services using a DSL, where we then generate a swagger model. But it also kills me that I need to add the Scala libraries, just for that. And also the issue with mixing Scala 2.10 x 2.11 versions and whatnot.

And yeah a pure Java based solution would be even better. And if Swagger could has as few 3rd party JAR dependencies.

Scala is cool et all, but not for something like this, where your library must be as light and less invasive as possible. Then old school pure Java code is IMHO the best.

Yura Vasko replied on Fri, 2014/08/29 - 5:47am

To split your application into smaller chunks (bundles/modules) you can consider deployment into OSGI environment. 

After that you have to redeploy only your application w/o swagger

Ron Ratovsky replied on Sat, 2014/08/30 - 9:24am

 I'll start with full disclosure - I'm part of the team behind Swagger.

I always enjoy getting feedback from users as it helps us understand what and how we should improve.

I'd like to clarify a few things, and then share some news that you may find interesting.

I'll start by saying that Swagger is a specification and not a tool. Swagger's eco-system has a set of tools around it, some of it were produced by the core team and others by third-party developers (which we more than welcome).

Regarding the files - based on what you wrote near the end I assume what bothers you is the CORS. Just keep in mind that even though our samples enable CORS on pretty much everything, you can enable it on the /api-docs* alone (or whichever endpoint you use).

You also mentioned the integration with Spring MVC. I assume that you use swagger-springmvc (though there are other libraries as well). This is one of the third-party libraries I was referring to above, and in my experience, they try to accommodate to users' requests, so feel free to open issues on their repository.

Now for the news and its effects - we are very close to releasing the next version of the Swagger specification, aka, Swagger 2.0. The new version of the spec includes quite a few changes and additions and it will affect tools all over. I will not go into details right now as to what's going to be included in it, but I'll give you two points that relate to the issues you've mentioned above.

The first, the specification changes so that everything is placed in a single file. It can be in several files, but it's not a requirement.

The second, the swagger-core version to support Swagger 2.0 is being migrated to Java. Scala will still be there for tests, but will not be included in the jars. There are historical reasons why Scala was used, but that's not really relevant. As for the pom clean-up, I'm not sure we'll get around to it for the upcoming release, but I believe that the major release following that one would be quite different.

I invite you to join our google group and voice your opinions, concerns and ideas there, so together we can keep on improving Swagger.

Lieven Doclo replied on Sat, 2014/08/30 - 11:40am in response to: Ron Ratovsky

 Ron,

Thanks for your reply. It's great to hear that the issues I pointed out are being addressed. However, I still don't see how you can use swagger in a distributed microservice environment: you'll still have a single swagger spec file per deployment. What would really help is to have an aggregator that merges multiple swagger files into a single one (something like what Netflix does with Turbine for real-time streams like Hystrix).

That being said, I also wrote a follow-up on the article describing possible alternatives to Swagger. Swagger, as it currently stands, is a top down approach. This sort of limits the use of Swagger to documentation only (like Javadoc). Frameworks like RAML work bottom up, enabling you to specify the API first and write the implementation afterwards (unit testing as you go against the specification). With 2.0, it looks like you're going the same way. In fact, reading your site you're almost copying what RAML does already, except for some (albeit cool) minor additions. So why would I choose Swagger 2.0 over RAML (which actually has none of the Swagger's current annoyances)? It's also dead-easy to use with Spring MVC. On that subject, I still baffles me you don't include support for Spring MVC out of the box! You support Play, Dropwizard, CXF, Resteasy, ... but you don't support the most popular web framework (I'm not saying that, the statistics do) and leave it up to an external library to do the integration. Again, another dependency and another possibility on unwanted transitive dependencies.

In any case, I'll join the Google group :).

Tony Tam replied on Sat, 2014/08/30 - 1:35pm

As Ron said, the next version will have jackson as a dependency and that's pretty much it.  Since *everything* depends on jackson, it shouldn't be an issue.

Tony Tam replied on Sat, 2014/08/30 - 1:39pm in response to: Lieven Doclo

Since Swagger is effectively a discoverable API interface, supported by a a strong suite of of tooling, it's short-sighted to compare it to RAML, which is a design-time modeling tool.  I do suggest you explore alternatives if you see them solving the same problem.

Lieven Doclo replied on Sat, 2014/08/30 - 2:52pm in response to: Tony Tam

With 2.0, they're going into the same realm like RAML and API BluePrint and at that point they will become real alternatives. And as for tooling, RAML is a specification (just like Swagger) and the toolset is a lot more extensive than what Swagger currently has to offer, including API Console which is effectively Swagger UI. So a correct feature comparison shows that Swagger actually offers a subset of what RAML can offer. And don't get me even started on API BluePrint's tooling suite.

Swagger is top-down until 2.0 whereas RAML is bottom-up. Will I use Swagger if it just need to document an API after it was implemented ? Sure (although nowadays you can generate RAML as well at which point you can use the API Console). Will I write a new API without design-time specs like RAML? No and at that point Swagger becomes useless. 

With 2.0, Swagger is completely going 'Not Invented Here' if I look at their statements on what 2.0 will offer and will fragment the contract-driven approach to implementing webservices even more. Swagger 2.0 is trying to solve a problem 2 frameworks already do.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.