search

dukecon / dukecon_server

MIT License
12 stars 6 forks source link

Remove direct Swagger dependency again, use JAX-RS Analyser Plugin again and adjust return values of controller methods for proper swagger.json generation #39

Open dasniko opened 8 years ago

dasniko commented 8 years ago

The direct Swagger dep was created to have a quick and dirty hack for producing a meaningful swagger.json, b/c the controller methods just return a Response object, which can't be detected usefully from the JAX-RS Analyser plugin. So, if we refactor the return values of the controller methods, we can use JAX-RS Analyser plugin again and can get rid of the superflous swagger deps and annotations.

dasniko commented 8 years ago

I tried several approaches in the meantime...

JAX-RS Analyser Plugin seems to have difficulties when it comes to nested elements and/or lists (which is also a kind of nesting) as return values. I don't know if this is a global problem of the plugin or if it's related to the fact that we are using Groovy and not Java classes (I guess, it's related to Groovy). It would have been a good choice, as the plugin also supports Asciidoc output, so we wouldn't have to go the loop over swagger to Asciidoc.

After trying to refactoring the JAX-RS classes to appropriate return objects, I realized, that this isn't possible for all cases, b/c our services deal with different http response status codes, and this shouldn't be done in other ways only for doc-purposes. This is also difficult (impossible) for the Swagger-Plugin to recognize, if this won't be documented manually. Despite all, the dependency to the swagger lib is ugly...

If we only produce the Swagger output to convert it to Asciidoctor, b/c we want to have a "readable" documentation, I would suggest to give the "Spring REST Doc" project a try, as this produces directly Ascidoc output and there's a mixture of generated and manually added content. I don't know this plugin yet, just read about it, but it sounds usable! Documentation: http://docs.spring.io/spring-restdocs/docs/current/reference/html5/ Sample Output: http://docs.spring.io/spring-restdocs/docs/current/samples/restful-notes/api-guide.html

@sippsack @ascheman

sippsack commented 8 years ago

But for spring Rest docs we have to switch from jax-rs to spring mvc annotations afaik.

We tried swagger because of swagger2markup which generates nice documemts with user defined custom blocks.

dasniko commented 8 years ago

So, why not refactor to pure Spring annotations?

sippsack commented 8 years ago

Why did we start with jax-rs anyway?

dasniko commented 8 years ago

Perhaps b/c it has a very much cleaner Annotation API to use... (and I know that it was me, who persisted to use the JAX-RS API)

But if this leads to pull in more and more dependencies and not gaining more functionality with them, it's worth rethinking the approach and refactor the application. If the goal is to have a readable documentation and you can drop 3 dependencies, it's more than worth it to give a try. (And the Spring REST Doc project produces also "nice documents" with the possibility to have "user defined custom blocks")

Decisions made at the beginning of a project are not carved into stone for infinity. Even more if the project has such a small codebase as this project has. Additionally, we are (luckily) NOT bound to any customer and can make our decisions on our own, also the refactoring decisions.