53.2. JBoss Fuse CXF Implementations
Overview
This section describes how to use the SwaggerFeature in JBoss Fuse CXF implementations, in which REST services are defined inside JAR files and deployed to a JBoss Fuse container or a fabric8 container.
Your JBoss 6.2.1 installation contains a Quickstart (installDir
/quickstarts/cxf/rest/) that demonstrates how to create a RESTful (JAX-RS) web service using CXF and how to enable Swagger and annotate the JAX-RS endpoints.
Enabling Swagger
Enabling Swagger involves:
- Modifying the XML file that defines the CXF service by adding the CXF class (
io.fabric8.cxf.endpoint.SwaggerFeature) to the<jaxrs:server>definition.For example:<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jaxrs="http://cxf.apache.org/blueprint/jaxrs" xmlns:cxf="http://cxf.apache.org/blueprint/core" xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd http://cxf.apache.org/blueprint/jaxrs http://cxf.apache.org/schemas/blueprint/jaxrs.xsd http://cxf.apache.org/blueprint/core http://cxf.apache.org/schemas/blueprint/core.xsd"> <!-- The <jaxrs:server/> element sets up our JAX-RS services. It defines: - the server's address, '/crm', relative to the default CXF servlet URI with the default settings the server will be running on 'http://localhost:8181/cxf/crm' - a list of service beans. in this example, we refer to another bean defined in this Blueprint XML file with a <ref/> element --> <jaxrs:server id="customerService" address="/crm"> <jaxrs:serviceBeans> <ref component-id="customerSvc"/> </jaxrs:serviceBeans> <jaxrs:providers> <bean class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider"/> </jaxrs:providers> <jaxrs:features> <bean class=“io.fabric8.cxf.endpoint.SwaggerFeature” /> <property name=“title” value=“Fabric8:CXF:Quickstarts - Customer Service” /> <property name=“description” value=“Sample REST-based Customer Service” /> <property name=“version” value=“${project.version}” /> </bean> </jaxrs:features> </jaxrs:server> <!-- We use the OSGi Blueprint XML syntax to define a bean referred to in the JAX-RS server setup. This bean carries a set of JAX-RS annotations that enable mapping its methods to incoming requests. --> <bean id="customerSvc" class="io.fabric8.quickstarts.rest.CustomerService"/> </blueprint> - In the REST resource class:
- Importing the Swagger API annotations for each annotation required by the service:
import com.wordnik.swagger.annotations.Api*where * = Api, ApiOperation, ApiParam, ApiResponse, ApiResponses, and so on.For details, see https://github.com/swagger-api/swagger-core/wiki/Annotations. - Adding Swagger annotations to the JAX-RS annotated endpoints (@PATH, @PUT, @POST, @GET, @Produces, @Consumes, @DELETE, @PathParam, and so on).For an example, see Example 53.2, “Example REST resource with Swagger annotations”.
Building and Deploying the Rest quickstart
See the README file in your JBoss Fuse 6.2.1 installDir
/quickstarts/cxf/rest/ directory for instructions on how to build and deploy the rest quickstart.
