Início
Produtos
Red Hat Fuse
7.1
Apache CXF Development Guide
Chapter 54. Extending JAX-RS Endpoints with Swagger Support

Este conteúdo não está disponível no idioma selecionado.

Chapter 54. Extending JAX-RS Endpoints with Swagger Support

Abstract

CXF includes a SwaggerFeature (org.apache.cxf.jaxrs.swagger.SwaggerFeature), which extends published JAX-RS endpoints with support for Swagger. Swagger is fundamentally a JSON-based format used to describe RESTful services, like its predecessors WSDL and WADL, but much easier to use. For a detailed description, see Swagger.

The SwaggerFeature is supported in both standalone CXF and in JBoss Fuse implementations.

54.1. Standalone CXF Implementations
Copiar o link

Overview
Copiar o link

This section describes how to use the SwaggerFeature in a standalone CXF implementation, in which REST services are defined inside WAR files and deployed to a standalone web server, such as Tomcat.

Note

The project should be a Maven WAR project. After building and packaging it, you can deploy it to Tomcat by dropping the WAR file into the $TOMCAT_HOME/webapps directory.

Enabling Swagger
Copiar o link

Enabling Swagger involves:

Modifying the XML file that defines the CXF service by adding the CXF class org.apache.cxf.jaxrs.swagger.SwaggerFeature to the <jaxrs:server> definition:
```
<jaxrs:server id="xx" address="/address" />
    <jaxrs:features>
        <bean class="org.apache.cxf.jaxrs.swagger.SwaggerFeature"/>
    </jaxrs:features>
</jaxrs:server>
```
```
<jaxrs:server id="xx" address="/address" />
    <jaxrs:features>
        <bean class="org.apache.cxf.jaxrs.swagger.SwaggerFeature"/>
    </jaxrs:features>
</jaxrs:server>
```
Copy to Clipboard Toggle word wrap
See Example 54.1, “Example Swagger-enabled Spring configuration” for an example of a Spring XML file for a Swagger-enabled CXF service.
In the REST resource class:
- Importing the Swagger API annotations for each annotation required by the service:
  import com.wordnik.swgger.annotations.Api*
  where * = Api, ApiOperation, ApiParam, ApiResponse, ApiResponses, and so on.
- Adding Swagger annotations to the JAX-RS annotated endpoints (@PATH, @PUT, @POST, @GET, @Produces, @Consumes, @DELETE, @PathParam, and so on).
  See Example 54.2, “Example REST resource with Swagger annotations” for an example of a Swagger-annotated REST resource class.

Configuration examples
Copiar o link

Example 54.1. Example Swagger-enabled Spring configuration

<beans
xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jaxrs="http://cxf.apache.org/jaxrs"
xsi:schemaLocation="
	http://www.springframework.org/schema/beans 
	http://www.springframework.org/schema/beans/spring-beans.xsd
	http://cxf.apache.org/jaxrs http://cxf.apache.org/schemas/jaxrs.xsd">

        <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>
               <!-- include Swagger Feature -->
               <bean class=“org.apache.cxf.jaxrs.swagger.SwaggerFeature” />
           </jaxrs:features>
       </jaxrs:server>

	</beans>

<beans
xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jaxrs="http://cxf.apache.org/jaxrs"
xsi:schemaLocation="
	http://www.springframework.org/schema/beans 
	http://www.springframework.org/schema/beans/spring-beans.xsd
	http://cxf.apache.org/jaxrs http://cxf.apache.org/schemas/jaxrs.xsd">

        <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>
               <!-- include Swagger Feature -->
               <bean class=“org.apache.cxf.jaxrs.swagger.SwaggerFeature” />
           </jaxrs:features>
       </jaxrs:server>

	</beans>

Copy to Clipboard

Toggle word wrap

This example shows only the relevant parts of a Swagger-annotated REST resource class.

Example 54.2. Example REST resource with Swagger annotations

...

import javax.annotation.Resource;
import javax.ws.rs.core.Context;
import javax.ws.rs.Consumes;
import javax.ws.rs.DELETE;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.Response;

import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.annotations.ApiOperation;
import com.wordnik.swagger.annotations.ApiParam;
import com.wordnik.swagger.annotations.ApiResponses;
import com.wordnik.swagger.annotations.ApiResponse;

…

@Path("/customerservice/")
@Api(value = "/customerservice", description = "Operations about customerservice")
public class CustomerService {

    private static final Logger LOG = LoggerFactory.getLogger(CustomerService.class);

    long currentId = 123;
    Map<Long, Customer> = customers = new HashMap<Long, Customer>();
    Map<Long, Order> orders = new HashMap<Long, Order>();
    private MessageContext jaxrsContext;

    public CustomerService() {
        init();
    }

   @GET
    @Path("/customers/{id}/")
    @Produces("application/xml")
    @ApiOperation(value = "Find Customer by ID", notes = "More notes about this method", response = Customer.class)
    @ApiResponses(value = {
            @ApiResponse(code = 500, message = "Invalid ID supplied"),
            @ApiResponse(code = 204, message = "Customer not found")
            })
    public Customer getCustomer(@ApiParam(value = "ID of Customer to fetch", required = true) @PathParam("id") String id) {
        LOG.info("Invoking getCustomer, Customer id is: {}", id);
        long idNumber = Long.parseLong(id);
        Customer c = customers.get(idNumber);
        return c;
    }

    @PUT
    @Path("/customers/")
    @Consumes({ "application/xml", "application/json" })
    @ApiOperation(value = "Update an existing Customer")
    @ApiResponses(value = {
            @ApiResponse(code = 500, message = "Invalid ID supplied"),
            @ApiResponse(code = 204, message = "Customer not found")
            })
    public Response updateCustomer(@ApiParam(value = "Customer object that needs to be updated", required = true) Customer customer) {
        LOG.info("Invoking updateCustomer, Customer name is: {}", customer.getName());
        Customer c = customers.get(customer.getId());
        Response r;
        if (c != null) {
            customers.put(customer.getId(), customer);
            r = Response.ok().build();
        } else {
            r = Response.notModified().build();
        }

        return r;
    }

    @POST
    @Path("/customers/")
    @Consumes({ "application/xml", "application/json" })
    @ApiOperation(value = "Add a new Customer")
    @ApiResponses(value = { @ApiResponse(code = 500, message = "Invalid ID supplied"), })
    public Response addCustomer(@ApiParam(value = "Customer object that needs to be updated", required = true) Customer customer) {
        LOG.info("Invoking addCustomer, Customer name is: {}", customer.getName());
        customer.setId(++currentId);

        customers.put(customer.getId(), customer);
        if (jaxrsContext.getHttpHeaders().getMediaType().getSubtype().equals("json")) {
            return Response.ok().type("application/json").entity(customer).build();
        } else {
            return Response.ok().type("application/xml").entity(customer).build();
        }
    }

    @DELETE
    @Path("/customers/{id}/")
    @ApiOperation(value = "Delete Customer")
    @ApiResponses(value = {
            @ApiResponse(code = 500, message = "Invalid ID supplied"),
            @ApiResponse(code = 204, message = "Customer not found")
            })
    public Response deleteCustomer(@ApiParam(value = "ID of Customer to delete", required = true) @PathParam("id") String id) {
        LOG.info("Invoking deleteCustomer, Customer id is: {}", id);
        long idNumber = Long.parseLong(id);
        Customer c = customers.get(idNumber);

     …
}

...

import javax.annotation.Resource;
import javax.ws.rs.core.Context;
import javax.ws.rs.Consumes;
import javax.ws.rs.DELETE;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.Response;

import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.annotations.ApiOperation;
import com.wordnik.swagger.annotations.ApiParam;
import com.wordnik.swagger.annotations.ApiResponses;
import com.wordnik.swagger.annotations.ApiResponse;

…

@Path("/customerservice/")
@Api(value = "/customerservice", description = "Operations about customerservice")
public class CustomerService {

    private static final Logger LOG = LoggerFactory.getLogger(CustomerService.class);

    long currentId = 123;
    Map<Long, Customer> = customers = new HashMap<Long, Customer>();
    Map<Long, Order> orders = new HashMap<Long, Order>();
    private MessageContext jaxrsContext;

    public CustomerService() {
        init();
    }

   @GET
    @Path("/customers/{id}/")
    @Produces("application/xml")
    @ApiOperation(value = "Find Customer by ID", notes = "More notes about this method", response = Customer.class)
    @ApiResponses(value = {
            @ApiResponse(code = 500, message = "Invalid ID supplied"),
            @ApiResponse(code = 204, message = "Customer not found")
            })
    public Customer getCustomer(@ApiParam(value = "ID of Customer to fetch", required = true) @PathParam("id") String id) {
        LOG.info("Invoking getCustomer, Customer id is: {}", id);
        long idNumber = Long.parseLong(id);
        Customer c = customers.get(idNumber);
        return c;
    }

    @PUT
    @Path("/customers/")
    @Consumes({ "application/xml", "application/json" })
    @ApiOperation(value = "Update an existing Customer")
    @ApiResponses(value = {
            @ApiResponse(code = 500, message = "Invalid ID supplied"),
            @ApiResponse(code = 204, message = "Customer not found")
            })
    public Response updateCustomer(@ApiParam(value = "Customer object that needs to be updated", required = true) Customer customer) {
        LOG.info("Invoking updateCustomer, Customer name is: {}", customer.getName());
        Customer c = customers.get(customer.getId());
        Response r;
        if (c != null) {
            customers.put(customer.getId(), customer);
            r = Response.ok().build();
        } else {
            r = Response.notModified().build();
        }

        return r;
    }

    @POST
    @Path("/customers/")
    @Consumes({ "application/xml", "application/json" })
    @ApiOperation(value = "Add a new Customer")
    @ApiResponses(value = { @ApiResponse(code = 500, message = "Invalid ID supplied"), })
    public Response addCustomer(@ApiParam(value = "Customer object that needs to be updated", required = true) Customer customer) {
        LOG.info("Invoking addCustomer, Customer name is: {}", customer.getName());
        customer.setId(++currentId);

        customers.put(customer.getId(), customer);
        if (jaxrsContext.getHttpHeaders().getMediaType().getSubtype().equals("json")) {
            return Response.ok().type("application/json").entity(customer).build();
        } else {
            return Response.ok().type("application/xml").entity(customer).build();
        }
    }

    @DELETE
    @Path("/customers/{id}/")
    @ApiOperation(value = "Delete Customer")
    @ApiResponses(value = {
            @ApiResponse(code = 500, message = "Invalid ID supplied"),
            @ApiResponse(code = 204, message = "Customer not found")
            })
    public Response deleteCustomer(@ApiParam(value = "ID of Customer to delete", required = true) @PathParam("id") String id) {
        LOG.info("Invoking deleteCustomer, Customer id is: {}", id);
        long idNumber = Long.parseLong(id);
        Customer c = customers.get(idNumber);

     …
}

Copy to Clipboard

Toggle word wrap

54.2. JBoss Fuse CXF Implementations
Copiar o link

Overview
Copiar o link

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 7.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
Copiar o link

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:

&lt;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
https://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"&gt;

   &lt;!-- The &lt;jaxrs:server/&gt; 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 &lt;ref/&gt; element    --&gt;

   &lt;jaxrs:server id="customerService" address="/crm"&gt;
       &lt;jaxrs:serviceBeans&gt;
           &lt;ref component-id="customerSvc"/&gt;
       &lt;/jaxrs:serviceBeans&gt;
       &lt;jaxrs:providers&gt;
           &lt;bean class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider"/&gt;
       &lt;/jaxrs:providers&gt;
       &lt;jaxrs:features&gt;
	      *&lt;bean class=“io.fabric8.cxf.endpoint.SwaggerFeature” /&gt;*
		   &lt;property name=“title” value=“Fabric8:CXF:Quickstarts - Customer Service” /&gt;
	   	&lt;property name=“description” value=“Sample REST-based Customer Service” /&gt;
		   &lt;property name=“version” value=“${project.version}” /&gt;
	      &lt;/bean&gt;
       &lt;/jaxrs:features&gt;
    &lt;/jaxrs:server&gt;


    &lt;!-- 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.  --&gt;

    &lt;bean id="customerSvc" class="io.fabric8.quickstarts.rest.CustomerService"/&gt;

&lt;/blueprint&gt;

&lt;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
https://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"&gt;

   &lt;!-- The &lt;jaxrs:server/&gt; 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 &lt;ref/&gt; element    --&gt;

   &lt;jaxrs:server id="customerService" address="/crm"&gt;
       &lt;jaxrs:serviceBeans&gt;
           &lt;ref component-id="customerSvc"/&gt;
       &lt;/jaxrs:serviceBeans&gt;
       &lt;jaxrs:providers&gt;
           &lt;bean class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider"/&gt;
       &lt;/jaxrs:providers&gt;
       &lt;jaxrs:features&gt;
	      *&lt;bean class=“io.fabric8.cxf.endpoint.SwaggerFeature” /&gt;*
		   &lt;property name=“title” value=“Fabric8:CXF:Quickstarts - Customer Service” /&gt;
	   	&lt;property name=“description” value=“Sample REST-based Customer Service” /&gt;
		   &lt;property name=“version” value=“${project.version}” /&gt;
	      &lt;/bean&gt;
       &lt;/jaxrs:features&gt;
    &lt;/jaxrs:server&gt;


    &lt;!-- 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.  --&gt;

    &lt;bean id="customerSvc" class="io.fabric8.quickstarts.rest.CustomerService"/&gt;

&lt;/blueprint&gt;

Copy to Clipboard

Toggle word wrap

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 54.2, “Example REST resource with Swagger annotations”.

Building and Deploying the Rest quickstart
Copiar o link

See the README file in your JBoss Fuse 7.1 installDir/quickstarts/cxf/rest/ directory for instructions on how to build and deploy the rest quickstart.

Voltar ao topo

Este conteúdo não está disponível no idioma selecionado.

Chapter 54. Extending JAX-RS Endpoints with Swagger Support

54.1. Standalone CXF Implementations
Copiar o link

Overview
Copiar o link

Enabling Swagger
Copiar o link

Configuration examples
Copiar o link

54.2. JBoss Fuse CXF Implementations
Copiar o link

Overview
Copiar o link

Enabling Swagger
Copiar o link

Building and Deploying the Rest quickstart
Copiar o link

Aprender

Experimente, compre e venda

Comunidades

Sobre a documentação da Red Hat

Tornando o open source mais inclusivo

Sobre a Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

Este conteúdo não está disponível no idioma selecionado.

Chapter 54. Extending JAX-RS Endpoints with Swagger Support

54.1. Standalone CXF ImplementationsCopiar o linkLink copiado para a área de transferência!

OverviewCopiar o linkLink copiado para a área de transferência!

Enabling SwaggerCopiar o linkLink copiado para a área de transferência!

Configuration examplesCopiar o linkLink copiado para a área de transferência!

54.2. JBoss Fuse CXF ImplementationsCopiar o linkLink copiado para a área de transferência!

OverviewCopiar o linkLink copiado para a área de transferência!

Enabling SwaggerCopiar o linkLink copiado para a área de transferência!

Building and Deploying the Rest quickstartCopiar o linkLink copiado para a área de transferência!

Aprender

Experimente, compre e venda

Comunidades

Sobre a documentação da Red Hat

Tornando o open source mais inclusivo

Sobre a Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

54.1. Standalone CXF Implementations
Copiar o link

Overview
Copiar o link

Enabling Swagger
Copiar o link

Configuration examples
Copiar o link

54.2. JBoss Fuse CXF Implementations
Copiar o link

Overview
Copiar o link

Enabling Swagger
Copiar o link

Building and Deploying the Rest quickstart
Copiar o link