search

wisdom-framework / wisdom

A modular and dynamic web framework
http://wisdom-framework.org
Apache License 2.0
88 stars 42 forks source link

Use swagger (or other API documentation tool) with wisdom #412

Closed vcavel closed 9 years ago

vcavel commented 9 years ago

Swagger is a really neat tool to generate a very nice interactive documentation for a REST API. It's fairly easy to integrate with JAX-RS, it automatically generates and serves your documentation, it is really really cool!

I am having the hardest time to integrate it with wisdom framework though, there is a project (https://github.com/livingobjects/wisdom-swagger) that aims at simplifying things but it seems that it will only serve the swagger documentation that you need to previously write, which is not ideal!

First question : Does anyone have had any success using swagger with wisdom? Second question : Does anyone have had any success in using some tool that generates a nicer documentation than the javadoc and make it play nicely with wisdom, a swagger equivalent?

If those 2 questions get a "no" answer, wouldn't it be super amazing to have a fully automatic generation of a swagger documentation for the REST APIs that we make using wisdom? That would be a super nice feature no?

Swagger's demo : http://petstore.swagger.wordnik.com/#!/pet

cescoffier commented 9 years ago

Hi,

I really like the idea. I did a first study to understand how we can populate Swagger metadata from the metadata Wisdom keep. It's not straightforward but possible.

About something equivalent to Swagger, I've tried a couple of things, but Swagger is definitely the most advanced, and flexible. However, it miss a couple of features:

And to answer to your last question, Yes, having Swagger support would be just awesome.

PS: I was not able to build your code, some dependencies were missing.

vcavel commented 9 years ago

For the websockets issue, it might be possible to use the annotation syntax of swagger (https://github.com/swagger-api/swagger-core/wiki/Annotations) to annotate the web socket services themselves. If the architecture of the websockets project is made correctly you should have well separated services and methods for every websocket calls (getUser, saveUser, ...), so annotating those would be fairly developer friendly!

I honestly have no idea on how to make it play nicely with wisdom, I'm just throwing it in there!

I did not provide any code that was mine, the wisdom-swagger project is something I found on github, I didn't take part in it!

cescoffier commented 9 years ago

Hi,

Oh sorry about the mistakes. I was thinking you did the wisdom-swagger extension.

About the web sockets, yes we should be able to massage Swagger to get something.

are you going to have a look into this ?

vcavel commented 9 years ago

Hi Clément,

I'm not really planning on it, it doesn't sound like a minor task (at all) and I don't think that I can give it the time it deserves, sorry!

Let's leave that pending for now and hope that a good soul wants to help or that I can make time for it in the future!

barjo commented 9 years ago

Hi,

I will try to have a look at it, but It may takes quite some time.

cescoffier commented 9 years ago

Cool !

We should first design a battle plan, I probably will help

cescoffier commented 9 years ago

@barjo is looking at RAML.

cescoffier commented 9 years ago

For information, here is @barjo work: https://github.com/barjo/wisdom-raml

It's already in a nice shape.

barjo commented 9 years ago

The project has been moved into the extensions https://github.com/wisdom-framework/wisdom/tree/master/extensions/wisdom-raml. Feel free to give it a try :eyes: