L2p Service Migration v0.3 to v0.4 - rwth-acis/las2peer-template-project GitHub Wiki

LAS2peer v0.3 to v0.4 Service Migration Guide

Swagger 2.0 and RESTMapper

With LAS2peer v0.4 we upgraded to Swagger 2.0. In order to make development easier and less confusing we removed the old Swagger 1.2 implementation and (REST-)annotations.

First you have to check and update your build file. Otherwise Ivy will not retrieve all dependencies. Check your build.xml for the line <ivy:retrieve type="jar" /> usually located in the get dependencies build target and replace it with <ivy:retrieve type="jar, bundle" />.

This means you have to remove old imports from i5.las2peer.restMapper.annotations.* and replace them with imports from the javax.ws.rs.* package. The annotation names basically stay the same, but the annotation field is 'name' now called 'value'.

Furthermore you have to replace imports from i5.las2peer.restMapper.annotations.swagger.* with imports from io.swagger.annotations.*. Here the @Summary and @Notes method annotations merged into @ApiOperation. This means @Summary("summary text") and @Notes("very large notes text") become @ApiOperation(value = "summary text", notes = "very large notes text"). Migration like this can be done with a regex.

search:

@Summary\("(.*)"\)\n(\s+)@Notes\("(.*)"\)\n

replace:

@ApiOperation\(value = "\1",\n\2notes = "\3"\)\n

The value defaultValue is now handled as an annotation itself. In conclusions this means you have to change annotations like @QueryParam(name = "test", defaultValue = "0") to @QueryParam(value = "test") @DefaultValue(value = "0") or even shorter @QueryParam("test") @DefaultValue("0"). Which can be done with some kind of regex.

search:

@(\S*)Param\(name\s*=\s*(.*),\s*defaultValue\s*=\s*([^\)]*)\)

replace:

@\1Param\(\2\) @DefaultValue\(\3\)

Furthermore please notice that all @Path annotations MUST start with a slash (/). This is a Swagger 2.0 requirement. Again it can be checked and corrected by regex.

search:

@Path\("([^/])

replace:

@Path\("/\1

Each LAS2peer service has to be annotated with @Api and @SwaggerDefinition replacing old @ApiInfo to generate a Swagger documentation. Please take a look at the TemplateProject as example.

Last but not least you may want to check out some other Swagger annotations.