I am a long time user of Swagger and am fairly happy with it. I immediately ruled out API Blueprints because there's no Java implementation. I use Ruby everyday (almost) but I still find using Java and Ruby together sometimes difficult even with the presence of JRuby.
RAML popped up a while ago and formed a working group and this spurred some activity on the Swagger side, they are both funded efforts. Swagger has some interesting associated tools, the only drawback for me personally is much of this is written in Scala. I'm indifferent to Scala, if people are productive with it that's great, but I don't want to learn another Java-like language to use/extend a tool. The area where this affected me is that I wanted to dynamically generate the Swagger documents from JAXRS annotations at runtime but this means you have to include the Scala runtime which was a showstopper for my project. But to use the Javascript console you only need to produce the documents. You can use the use the swagger doclet[1] to produce the document from JAXRS annotation, create the document manually, or use whatever other means. I just wrote a small tool to scan the annotations and produce the document. But once you have the document the console[2] is great and you can use all the nifty client generators which are very handy. Once the console is working the Javascript client is generated on the fly. The Javascript console is a straight forward Backbone application so it's fairly easy to augment/extend. The RAML tools look great and I have a lot of respect for the guys at MuleSoft but just haven't had time to play with it. [1]: https://github.com/ryankennedy/swagger-jaxrs-doclet [2]: https://github.com/swagger-api/swagger-ui On Nov 17, 2014, at 11:08 PM, Jeff Jensen <jeffjen...@upstairstechnology.com> wrote: > Some additional ones to consider: > Swagger [0] > API BluePrint [1] > RAML [2] > > I find the most ecosystem around Swagger; seems the most popular. Nice list > of integrations (see the link to Maven plugin) [3] > > [0] http://swagger.io > [1] http://apiblueprint.org > [2] http://raml.org > [3] https://github.com/swagger-api/swagger-spec#additional-libraries > > > On Mon, Nov 17, 2014 at 7:55 PM, Martin Todorov <carlspr...@gmail.com> > wrote: > >> Hi, >> >> Perhaps this isn't the right mailing list, but it's partially >> Maven-related... >> >> I've been wondering: are there some existing API-s and Maven plugins that >> can generate either of the following: >> a) Javadoc generators for REST API-s >> b) Markdown-styled documentation generators for REST API-s >> >> I'm aware of Enunciate... Is that the only option, or are there any others >> that can be used with Maven plugins? >> >> Thanks in advance for any hints! >> Kind regards, >> >> Martin Todorov >> Thanks, Jason ---------------------------------------------------------- Jason van Zyl Founder, Apache Maven http://twitter.com/jvanzyl http://twitter.com/takari_io --------------------------------------------------------- People develop abstractions by generalizing from concrete examples. Every attempt to determine the correct abstraction on paper without actually developing a running system is doomed to failure. No one is that smart. A framework is a resuable design, so you develop it by looking at the things it is supposed to be a design of. The more examples you look at, the more general your framework will be. -- Ralph Johnson & Don Roberts, Patterns for Evolving Frameworks
