Swaggerize API

[WesGilster]

I've started adding the annotations to our API. Putting documentation generation aside, one question we have to figure out is if we want swagger UI permanently available from within Photonic3D? Here is an example of swagger UI: http://jmchung.github.io/blog/2013/12/14/integrating-swagger-into-jax-rs-with-java-ee-6-specification/

If we want to keep our dependencies to a minimum, then we just need to add: swagger-annotations-1.5.3-M1.jar to our regular build and then swagger ui won't be available from our web content.

That means we'll need a whole new build, or instead(what I suggest), is that we can make Swagger UI available from within our existing testkit build. Then we'll add all of the rest of the jars into this build, we'll need to somehow know when CWH was start.sh'd in testkit mode so that I know when I need to add the following resources to our ApplicationConfig:

        resources.add(com.wordnik.swagger.jaxrs.listing.ApiListingResource.class);
        resources.add(com.wordnik.swagger.jaxrs.listing.ApiDeclarationProvider.class);
        resources.add(com.wordnik.swagger.jaxrs.listing.ApiListingResourceJSON.class);
        resources.add(com.wordnik.swagger.jaxrs.listing.ResourceListingProvider.class);

as this doc describes: http://jmchung.github.io/blog/2013/12/14/integrating-swagger-into-jax-rs-with-java-ee-6-specification/

[jmkao]

I can try it both ways; I kind of like the idea of having swagger always available in the main server to encourage the path of using it, but I'll have to see what effect that has on the speed and size of the builds.

[WesGilster]

Sounds good to me, it would certainly attract developers. I just don't want anyone to shy away due to our growing jar dependencies.

[jmkao]

In order to get the swagger build to work easily, I'm probably going to need to move more parts of the build to gradle building conventions. Once that reaches a certain critical mass, I'll move all the old dependencies over to gradle as well, which will make dependency management easier, and we can focus more on optimizing the overall size of the distribution rather than the specific number of libraries.

On Mon, Mar 28, 2016 at 9:51 PM, Wes G. notifications@github.com wrote:

Sounds good to me, it would certainly attract developers. I just don't want anyone to shy away due to our growing jar dependencies.

— You are receiving this because you commented. Reply to this email directly or view it on GitHub https://github.com/area515/Creation-Workshop-Host/issues/192#issuecomment-202710427 !DSPAM:56fa09d2135736845892514!

[WesGilster]

Ergobot mentioned that he's done some conversion of this stuff over to gradle already.

@ergobot Could you create a PR to jmkao so he doesn't have to reinvent anything and see what he can take from your work...

[ergobot]

project is cwh-gradle

Moved the packages around to get work with gradle structure build.gradle has all dependencies needed - uses spring in the build.gradle, i couldn't find the mp4parser dependency that was used. JettySecurityUtils needs a reference to jdk for the certificate stuff, couldn't figure that out on the first go. PrinterService.java has one method as an example

[jmkao]

I have ergo's changes in a local clone. They look good, although it's quite a lot of changes, especially to structure, to do in a single pass. I'm going to phase it out in the following steps:

1. Build into the maven/gradle output structure based on existing src and lib structure
2. Update packaging of zips to work out of the maven/gradle output structure
3. Update src structure to maven/gradle structure
4. Migrate easy libs to gradle dependencies

That way, only step 3 needs to be coordinated across forks to pick a time after all major changes have been pushed into area515 so that source changes don't need to be merged with source code structure changes, which would require manual effort.

The timing for step 3 would probably be good right after a major release (maybe a "Photonic 1.0" release) and would also be a good time to scrub the binary history of the area515 repo (which will take it from 1.6G to <100MB).

[WesGilster]

@jmkao Cool whatever you can utilize...

@ergobot I didn't realize you made a whole new repo for that, I thought it was just going to be a branch PR.