What is the benefit of using Spring REST Docs comparing to Swagger

api rest compare swagger spring-restdocs
evgeniy44 picture evgeniy44 · Dec 24, 2015 · Viewed 13.4k times · Source

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.

Answer

Edgar Ngwenya picture Edgar Ngwenya · Jan 16, 2016

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.

Related questions

How do I make calls to a REST API using C#?

This is the code I have so far: using System; using System.Collections.Generic; using System.Linq; using System.Text; using System; using System.Net.Http; using System.Web; using System.Net; using System.IO; namespace ConsoleProgram { public class Class1 { …

Read More
How do you set the Content-Type header for an HttpClient request?

I'm trying to set the Content-Type header of an HttpClient object as required by an API I am calling. I tried setting the Content-Type like below: using (var httpClient = new HttpClient()) { httpClient.BaseAddress = new Uri("http://example.com/"); httpClient.DefaultRequestHeaders.…

Read More
REST API Best practices: Where to put parameters?

A REST API can have parameters in at least two ways: As part of the URL-path (i.e. /api/resource/parametervalue ) As a query argument (i.e. /api/resource?parameter=value ) What is the best practice here? Are there any …

Read More