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 > > > > > > > > > >
