[DOSGI-270] Add swagger documentation example
Project: http://git-wip-us.apache.org/repos/asf/cxf-dosgi/repo Commit: http://git-wip-us.apache.org/repos/asf/cxf-dosgi/commit/be1d9b7b Tree: http://git-wip-us.apache.org/repos/asf/cxf-dosgi/tree/be1d9b7b Diff: http://git-wip-us.apache.org/repos/asf/cxf-dosgi/diff/be1d9b7b Branch: refs/heads/master Commit: be1d9b7ba01baa4528c7b71a843d30050d225830 Parents: ac8a037 Author: Christian Schneider <ch...@die-schneider.net> Authored: Mon Jul 10 12:15:20 2017 +0200 Committer: Christian Schneider <ch...@die-schneider.net> Committed: Mon Jul 10 12:15:20 2017 +0200 ---------------------------------------------------------------------- distribution/multi-bundle/pom.xml | 1 + distribution/repository/pom.xml | 3 +++ .../features/src/main/resources/features.xml | 3 +++ samples/rest/README.md | 7 ++++++- .../cxf/dosgi/samples/rest/TaskResource.java | 18 ++++++++++++++-- samples/rest/impl-jackson/pom.xml | 4 ++-- .../samples/rest/impl/TaskResourceImpl.java | 19 +++++------------ samples/rest/impl/pom.xml | 12 ++++++++++- .../samples/rest/impl/TaskResourceImpl.java | 22 +++++++++++++++++++- 9 files changed, 68 insertions(+), 21 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cxf-dosgi/blob/be1d9b7b/distribution/multi-bundle/pom.xml ---------------------------------------------------------------------- diff --git a/distribution/multi-bundle/pom.xml b/distribution/multi-bundle/pom.xml index 58cb4db..633bb08 100644 --- a/distribution/multi-bundle/pom.xml +++ b/distribution/multi-bundle/pom.xml @@ -65,6 +65,7 @@ <descriptor>mvn:org.apache.cxf.dosgi/cxf-dosgi/${project.version}/xml/features</descriptor> </descriptors> <features> + <feature>cxf-rs-description-swagger2</feature> <feature>cxf-dosgi-base</feature> <feature>aries-rsa-discovery-zookeeper</feature> <feature>cxf-dosgi-provider-ws</feature> http://git-wip-us.apache.org/repos/asf/cxf-dosgi/blob/be1d9b7b/distribution/repository/pom.xml ---------------------------------------------------------------------- diff --git a/distribution/repository/pom.xml b/distribution/repository/pom.xml index 45eb4da..a72ac6e 100644 --- a/distribution/repository/pom.xml +++ b/distribution/repository/pom.xml @@ -58,4 +58,7 @@ </dependency> </dependencies> + <properties> + <checkstyle.skip>true</checkstyle.skip> + </properties> </project> http://git-wip-us.apache.org/repos/asf/cxf-dosgi/blob/be1d9b7b/samples/features/src/main/resources/features.xml ---------------------------------------------------------------------- diff --git a/samples/features/src/main/resources/features.xml b/samples/features/src/main/resources/features.xml index 58b9c91..6d62713 100644 --- a/samples/features/src/main/resources/features.xml +++ b/samples/features/src/main/resources/features.xml @@ -19,6 +19,9 @@ <feature name="cxf-dosgi-sample-rest-impl" version="${project.version}"> <feature>cxf-dosgi-provider-rs</feature> <feature>aries-rsa-discovery-zookeeper-server</feature> + <feature>cxf-features-logging</feature> + <feature>cxf-rs-description-swagger2</feature> + <bundle>mvn:org.webjars/swagger-ui/2.2.10-1</bundle> <bundle>mvn:org.apache.cxf.dosgi.samples/cxf-dosgi-samples-rest-api/${project.version}</bundle> <bundle>mvn:org.apache.cxf.dosgi.samples/cxf-dosgi-samples-rest-impl/${project.version}</bundle> </feature> http://git-wip-us.apache.org/repos/asf/cxf-dosgi/blob/be1d9b7b/samples/rest/README.md ---------------------------------------------------------------------- diff --git a/samples/rest/README.md b/samples/rest/README.md index eda3e1d..2a7311b 100644 --- a/samples/rest/README.md +++ b/samples/rest/README.md @@ -40,13 +40,18 @@ task:add 4 Mytask task:list ``` +### Browse Swagger documentation + +The jaxrs sample also creates swagger documentation for the REST endpoint. + +[Get the swagger documentation for the jaxrs sample] (http://localhost:8181/cxf/tasks/api-docs?url=../swagger.json). + ### Add logging intent Starting with CXF 3.1.9 the CXF logging feature is exported as an intent by default this makes it very easy to add logging to the rest example. ``` -feature:install cxf-features-logging config:property-set -p TaskResource service.exported.intents logging endpoint http://localhost:8181/cxf/tasks ``` http://git-wip-us.apache.org/repos/asf/cxf-dosgi/blob/be1d9b7b/samples/rest/api/src/main/java/org/apache/cxf/dosgi/samples/rest/TaskResource.java ---------------------------------------------------------------------- diff --git a/samples/rest/api/src/main/java/org/apache/cxf/dosgi/samples/rest/TaskResource.java b/samples/rest/api/src/main/java/org/apache/cxf/dosgi/samples/rest/TaskResource.java index 2ccedb6..15630f7 100644 --- a/samples/rest/api/src/main/java/org/apache/cxf/dosgi/samples/rest/TaskResource.java +++ b/samples/rest/api/src/main/java/org/apache/cxf/dosgi/samples/rest/TaskResource.java @@ -26,22 +26,36 @@ import javax.ws.rs.PathParam; import javax.ws.rs.Produces; import io.swagger.annotations.Api; +import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiResponse; +import io.swagger.annotations.ApiResponses; -@Api +@Api(tags = {"tasks"}) @Path("") @Produces("application/xml") public interface TaskResource { + + @ApiOperation(value = "Get task by ID", notes = "Returns a single task", response = Task.class) + @ApiResponses(value = { + @ApiResponse(code = 404, message = "Task not found") + }) @GET @Path("/{id}") Task get(@PathParam("id") Integer id); + @ApiOperation(value = "Add task or update existing task") @PUT void addOrUpdate(Task task); + @ApiOperation(value = "Deletes a task") + @ApiResponses(value = { + @ApiResponse(code = 404, message = "Task not found") + }) @DELETE @Path("/{id}") void delete(Integer id); - + + @ApiOperation(value = "Retrieve all tasks") @GET Task[] getAll(); } http://git-wip-us.apache.org/repos/asf/cxf-dosgi/blob/be1d9b7b/samples/rest/impl-jackson/pom.xml ---------------------------------------------------------------------- diff --git a/samples/rest/impl-jackson/pom.xml b/samples/rest/impl-jackson/pom.xml index 1ed144f..3b79b52 100644 --- a/samples/rest/impl-jackson/pom.xml +++ b/samples/rest/impl-jackson/pom.xml @@ -41,13 +41,13 @@ <dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-rs-service-description-swagger</artifactId> - <version>3.1.9</version> + <version>${cxf.version}</version> <scope>provided</scope> </dependency> <dependency> <groupId>org.apache.aries.rsa</groupId> <artifactId>org.apache.aries.rsa.spi</artifactId> - <version>1.9.0</version> + <version>${aries.rsa.version}</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.jaxrs</groupId> http://git-wip-us.apache.org/repos/asf/cxf-dosgi/blob/be1d9b7b/samples/rest/impl-jackson/src/main/java/org/apache/cxf/dosgi/samples/rest/impl/TaskResourceImpl.java ---------------------------------------------------------------------- diff --git a/samples/rest/impl-jackson/src/main/java/org/apache/cxf/dosgi/samples/rest/impl/TaskResourceImpl.java b/samples/rest/impl-jackson/src/main/java/org/apache/cxf/dosgi/samples/rest/impl/TaskResourceImpl.java index f1855de..8531559 100644 --- a/samples/rest/impl-jackson/src/main/java/org/apache/cxf/dosgi/samples/rest/impl/TaskResourceImpl.java +++ b/samples/rest/impl-jackson/src/main/java/org/apache/cxf/dosgi/samples/rest/impl/TaskResourceImpl.java @@ -24,16 +24,17 @@ import java.util.HashMap; import java.util.List; import java.util.Map; -import com.fasterxml.jackson.jaxrs.json.JacksonJaxbJsonProvider; -import io.swagger.annotations.Api; import org.apache.cxf.dosgi.common.api.IntentsProvider; import org.apache.cxf.dosgi.samples.rest.Task; import org.apache.cxf.dosgi.samples.rest.TaskResource; import org.apache.cxf.ext.logging.LoggingFeature; import org.apache.cxf.feature.Features; -import org.apache.cxf.jaxrs.swagger.Swagger2Feature; import org.osgi.service.component.annotations.Component; +import com.fasterxml.jackson.jaxrs.json.JacksonJaxbJsonProvider; + +import io.swagger.annotations.Api; + @Component// (// immediate = true, // @@ -89,17 +90,7 @@ public class TaskResourceImpl implements TaskResource, IntentsProvider { @Override public List<?> getIntents() { - return asList(createSwaggerFeature(), new JacksonJaxbJsonProvider()); - } - - private Swagger2Feature createSwaggerFeature() { - Swagger2Feature swagger = new Swagger2Feature(); - //swagger2Feature.setBasePath("/cxf/"); - swagger.setUsePathBasedConfig(true); - swagger.setPrettyPrint(true); - swagger.setSupportSwaggerUi(true); - swagger.setScan(false); - return swagger; + return asList(new JacksonJaxbJsonProvider()); } } http://git-wip-us.apache.org/repos/asf/cxf-dosgi/blob/be1d9b7b/samples/rest/impl/pom.xml ---------------------------------------------------------------------- diff --git a/samples/rest/impl/pom.xml b/samples/rest/impl/pom.xml index 5e28d36..be0591b 100644 --- a/samples/rest/impl/pom.xml +++ b/samples/rest/impl/pom.xml @@ -37,7 +37,17 @@ <groupId>org.apache.aries.rsa</groupId> <artifactId>org.apache.aries.rsa.spi</artifactId> <version>1.9.0</version> - <type>bundle</type> + </dependency> + <dependency> + <groupId>org.apache.cxf.dosgi</groupId> + <artifactId>cxf-dosgi-common</artifactId> + <version>${project.version}</version> + </dependency> + <dependency> + <groupId>org.apache.cxf</groupId> + <artifactId>cxf-rt-rs-service-description-swagger</artifactId> + <version>${cxf.version}</version> + <scope>provided</scope> </dependency> </dependencies> http://git-wip-us.apache.org/repos/asf/cxf-dosgi/blob/be1d9b7b/samples/rest/impl/src/main/java/org/apache/cxf/dosgi/samples/rest/impl/TaskResourceImpl.java ---------------------------------------------------------------------- diff --git a/samples/rest/impl/src/main/java/org/apache/cxf/dosgi/samples/rest/impl/TaskResourceImpl.java b/samples/rest/impl/src/main/java/org/apache/cxf/dosgi/samples/rest/impl/TaskResourceImpl.java index 3b3e400..c4171bd 100644 --- a/samples/rest/impl/src/main/java/org/apache/cxf/dosgi/samples/rest/impl/TaskResourceImpl.java +++ b/samples/rest/impl/src/main/java/org/apache/cxf/dosgi/samples/rest/impl/TaskResourceImpl.java @@ -18,11 +18,16 @@ */ package org.apache.cxf.dosgi.samples.rest.impl; +import static java.util.Arrays.asList; + import java.util.HashMap; +import java.util.List; import java.util.Map; +import org.apache.cxf.dosgi.common.api.IntentsProvider; import org.apache.cxf.dosgi.samples.rest.Task; import org.apache.cxf.dosgi.samples.rest.TaskResource; +import org.apache.cxf.jaxrs.swagger.Swagger2Feature; import org.osgi.service.component.annotations.Component; @Component// @@ -36,7 +41,7 @@ import org.osgi.service.component.annotations.Component; "org.apache.cxf.rs.address=/tasks" // } // ) -public class TaskResourceImpl implements TaskResource { +public class TaskResourceImpl implements TaskResource, IntentsProvider { Map<Integer, Task> taskMap; public TaskResourceImpl() { @@ -73,4 +78,19 @@ public class TaskResourceImpl implements TaskResource { taskMap.remove(id); } + @Override + public List<?> getIntents() { + return asList(createSwaggerFeature()); + } + + private Swagger2Feature createSwaggerFeature() { + Swagger2Feature swagger = new Swagger2Feature(); + swagger.setDescription("Sample jaxrs application to organize taks"); + swagger.setTitle("Tasks sample"); + swagger.setUsePathBasedConfig(true); // Necessary for OSGi + swagger.setScan(false); + swagger.setPrettyPrint(true); + swagger.setSupportSwaggerUi(true); + return swagger; + } }
