Add Swagger extension

[jlouvel]

In addition to the WADL extension, it would be nice to be able to produce such HTML documentation and API description information from a live Restlet Application.
http://swagger.wordnik.com/

[jlouvel]

Swagger forces some strict URIs/representations conventions that can't match with the openess of Restlet based web APIs, We need to explore other approaches.

[ggodlewski]

Hi,
I created simple extension for swagger: https://github.com/ggodlewski/org.restlet.ext.swagger
At the moment it works only with JAX-RS resources but it would be easy to add ServerResource support.

[jlouvel]

@ggodlewski Excellent, thanks for working on this. Could you explain a bit more how the extension is working and if there are any special limitation?

If possible, an adaptation to ServerResource/Restlet API would be awesome. Do you think it is feasible?

[ggodlewski]

The usage is simple. You put SwaggerApiDocsRestlet on specific route ("/api-docs/swagger.json" for instance) and point it the API root with: swaggerApiDocsRestlet.setApiInboundRoot(router);
It iterates recursively (SwaggerRestletIterator) through restelets and search for JaxRsRestlet
When JaxRsRestlet is found Documentation is generated with SwaggerJaxRsResourceGenerator
To add ServerResource just copy SwaggerJaxRsResourceGenerator, modify some annotation processing and add "if" in here https://github.com/ggodlewski/org.restlet.ext.swagger/blob/master/src/org/restlet/ext/swagger/SwaggerApiDocsRestlet.java#L94

There are some things to do with JaxRs generation as well, but I'm blocked by #746 . If anybody helps with this issue I can put this ext into incubator and create pull request.

[BryanHunt]

@ggodlewski Any chance you could do the changes needed to support ServerResource? I'd really like to give this a try in the OSGi edition.

[jlouvel]

I'm sure we could reuse the introspection logic in the WADL extension to support ServerResource with Swagger extension as well, an maybe factorize some code.

I wish I had more time to work on this :) @thboileau can you have a stab at this?

[clakech]

yes @thboileau could you have a lot at this? seems to complex to me :(

[jlouvel]

Now that the 2.2 build and tests have been fixed, Thierry will add the Swagger extension (in its current state) for 2.2 RC1 (due tomorrow). Stay tuned.

[jlouvel]

We'll add support for Restlet API introspection later on, ideally for 2.2.0 if someone can take a stab at it

[clakech]

Very very cool news! I'am in strating blocks!

[jlouvel]

From @thboileau: I've still issue with swagger extension (it relies on scala code, I'm not sure what to do with that). I think the thymeleaf extension is easier to integrate.

---

I saw only those Java source classes: https://github.com/ggodlewski/org.restlet.ext.swagger/tree/master/src/org/restlet/ext/swagger

IMO, no problem with the Scala lib dependency, it is still Java byte code in the end. For reference:
http://repo1.maven.org/maven2/com/wordnik/swagger-core_2.10/1.3.2/swagger-core_2.10-1.3.2.pom