Hi,
Thanks for sharing your experiences!
I will have a look at the links you guys sent me. After learning about
Swagger, I have come across:
https://github.com/kongchen/swagger-maven-plugin
RAML looks promising, but I don't think there's a Maven plugin for that.
Once again, thanks for your comments!
Kind regards,
Martin
On Tue, Nov 18, 2014 at 2:32 PM, Jason van Zyl ja...@takari.io wrote:
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
