CXF集成swagger

  swagger是一套OpenAPI规范，用于生成restful api接口描述，便于使用者发现、开发及集成。

  本文参考官方文档（http://cxf.apache.org/docs/swagger2feature.html），做的实例验证，为cxf 生成api文档描述。

  一、依赖包：

<dependency>
    <groupId>org.apache.cxfgroupId>
    <artifactId>cxf-rt-transports-httpartifactId>
    <version>3.2.0version>
dependency>

<dependency>
    <groupId>org.apache.cxfgroupId>
    <artifactId>cxf-rt-transports-http-jettyartifactId>
    <version>3.2.0version>
dependency>
<dependency>
    <groupId>org.apache.cxfgroupId>
    <artifactId>cxf-rt-frontend-jaxrsartifactId>
    <version>3.2.0version>
dependency>
<dependency>
    <groupId>org.apache.cxfgroupId>
    <artifactId>cxf-rt-rs-service-description-swaggerartifactId>
    <version>3.2.0version>
dependency>
<dependency>
    <groupId>javax.ws.rsgroupId>
    <artifactId>javax.ws.rs-apiartifactId>    
    <version>2.0.1version>
dependency>
<dependency>
  <groupId>com.fasterxml.jackson.jaxrsgroupId>
  <artifactId>jackson-jaxrs-json-providerartifactId>  
  <version>2.4.1version>dependency>

<dependency>  
  <groupId>org.springframeworkgroupId>
  <artifactId>spring-contextartifactId>

  <version>4.3.6.RELEASEversion>

dependency >
< dependency >
< groupId >org.springframework groupId >
< artifactId >spring-web artifactId >

   <version>4.3.6.RELEASEversion>

dependency >

<dependency>
    <groupId>org.springframeworkgroupId>
    <artifactId>spring-aopartifactId>
    <version>4.3.6.RELEASEversion>
dependency>
<dependency>
    <groupId>org.springframeworkgroupId>
    <artifactId>spring-aspectsartifactId>
    <version>4.3.6.RELEASEversion>
dependency>
<dependency>
    <groupId>org.springframeworkgroupId>
    <artifactId>spring-beansartifactId>
    <version>4.3.6.RELEASEversion>
dependency>

<dependency>
    <groupId>io.swaggergroupId>
    <artifactId>swagger-jaxrsartifactId>
    <version>1.5.16version>    
dependency>
<dependency>
    <groupId>io.swaggergroupId>
    <artifactId>swagger-annotationsartifactId>
    <version>1.5.16version>
dependency>
<dependency>
    <groupId>io.swaggergroupId>
    <artifactId>swagger-coreartifactId>
    <version>1.5.16version>
dependency>

<dependency>
    <groupId>org.apache.cxfgroupId>
    <artifactId>cxf-rt-rs-service-description-swaggerartifactId>
    <version>3.2.0version>
dependency>

<dependency>
    <groupId>org.webjarsgroupId>
    <artifactId>swagger-uiartifactId>
    <version>3.2.0version>
dependency>

二、cxf服务定义

Sample.java:

package com.test.cxf;

import io.swagger.annotations.*;

import javax.ws.rs.*;
import javax.ws.rs.core.Context;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.UriInfo;
import java.util.Collections;
import java.util.Map;
import java.util.TreeMap;

@Path("/sample")
@Api(value = "/sample", description = "Sample JAX-RS service with Swagger documentation")
public class Sample {
    private Map items;

    public Sample() {
        items = Collections.synchronizedMap(new TreeMap(String.CASE_INSENSITIVE_ORDER));
        items.put("Item 1", new Item("Item 1", "Value 1"));
        items.put("Item 2", new Item("Item 2", "Value 2"));
    }


    @Produces({ MediaType.APPLICATION_JSON })
    @GET
    @ApiOperation(
        value = "Get operation with Response and @Default value",
        notes = "Get operation with Response and @Default value",
        response = Item.class,
        responseContainer = "List"
    )
    public Response getItems(
        @ApiParam(value = "Page to fetch", required = true) @QueryParam("page") @DefaultValue("1") int page) {

        return Response.ok(items.values()).build();
    }

    @Produces({ MediaType.APPLICATION_JSON })
    @Path("/{name}")
    @GET
    @ApiOperation(
        value = "Get operation with type and headers",
        notes = "Get operation with type and headers",
        response = Item.class
    )
    public Item getItem(
        @ApiParam(value = "language", required = true) @HeaderParam("Accept-Language") final String language,
        @ApiParam(value = "name", required = true) @PathParam("name") String name) {
        return items.get(name);
    }

    @Consumes({ MediaType.APPLICATION_JSON })
    @POST
    @ApiOperation(
        value = "Post operation with entity in a body",
        notes = "Post operation with entity in a body",
        response = Item.class
    )
    public Response createItem(
        @Context final UriInfo uriInfo,
        @ApiParam(value = "item", required = true) final Item item) {
        items.put(item.getName(), item);
        return Response
            .created(uriInfo.getBaseUriBuilder().path(item.getName()).build())
            .entity(item).build();
    }

    @Produces({ MediaType.APPLICATION_JSON })
    @Path("/{name}")
    @PUT
    @ApiOperation(
        value = "Put operation with form parameter",
        notes = "Put operation with form parameter",
        response = Item.class
    )
    public Item updateItem(
        @ApiParam(value = "name", required = true) @PathParam("name") String name,
        @ApiParam(value = "value", required = true) @FormParam("value") String value) {
        Item item = new Item(name, value);
        items.put(name,  item);
        return item;
    }

    @Path("/{name}")
    @DELETE
    @ApiOperation(
        value = "Delete operation with implicit header",
        notes = "Delete operation with implicit header"
    )
    @ApiImplicitParams(
       @ApiImplicitParam(
           name = "Accept-Language",
           value = "language",
           required = true,
           dataType = "String",
           paramType = "header"
       )
    )
    public Response delete(@ApiParam(value = "name", required = true) @PathParam("name") String name) {
        items.remove(name);
        return Response.ok().build();
    }
}

Item.java

package com.test.cxf;

public class Item {
    private String name;
    private String value;

    public Item() {
    }

    public Item(final String name, final String value) {
        this.name = name;
        this.value = value;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getValue() {
        return value;
    }

    public void setValue(String value) {
        this.value = value;
    }
}

三、cxf spring配置文件

spring.xml

xml version="1.0" encoding="UTF-8"?>
<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-4.0.xsd
       http://cxf.apache.org/jaxrs
       http://cxf.apache.org/schemas/jaxrs.xsd">

    <bean id = "swagger2Feature" class="org.apache.cxf.jaxrs.swagger.Swagger2Feature">
        <property name="basePath" value="/sample-web/ws" />
    bean>
    <bean id="jacksonProvider" class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider"/>

    <bean id="sample" class="com.test.cxf.Sample"/>

    <jaxrs:server address="/">
        <jaxrs:serviceBeans>
            <ref bean="sample"/>
        jaxrs:serviceBeans>
        <jaxrs:providers>
            <ref bean="jacksonProvider"/>
        jaxrs:providers>
        <jaxrs:features>
            <ref bean="swagger2Feature"/>
        jaxrs:features>
    jaxrs:server>

beans>

四、POM插件配置

swagger-ui解压拷贝到项目工程下

<build>
    <finalName>${project.artifactId}finalName>
    <plugins>
        <plugin>
            <groupId>org.apache.tomcat.mavengroupId>
            <artifactId>tomcat7-maven-pluginartifactId>
            <version>2.2version>
            <configuration>
                <server>tomcat7server>
                <port>8080port>
                <uriEncoding>UTF-8uriEncoding>
                <warSourceDirectory>${project.build.directory}/${project.artifactId}warSourceDirectory>
                <path>/${project.artifactId}path>
            configuration>
        plugin>

        <plugin>
            <groupId>org.apache.maven.pluginsgroupId>
            <artifactId>maven-compiler-pluginartifactId>
            <configuration>
                <source>1.7source>
                <target>1.7target>
            configuration>
        plugin>

        <plugin>
            <groupId>org.apache.maven.pluginsgroupId>
            <artifactId>maven-dependency-pluginartifactId>
            <version>2.9version>
            <executions>
                <execution>
                    <phase>generate-resourcesphase>
                    <goals>
                        <goal>unpackgoal>
                    goals>
                    <configuration>
                        <artifactItems>
                            <artifactItem>
                                <groupId>org.webjarsgroupId>
                                <artifactId>swagger-uiartifactId>
                                <version>2.1.0version>
                                <overWrite>trueoverWrite>
                                <outputDirectory>${project.build.directory}/swagger-uioutputDirectory>
                                <excludes>**/*.gzexcludes>
                            artifactItem>
                        artifactItems>
                    configuration>
                execution>
            executions>
        plugin>
        <plugin>
            <artifactId>maven-resources-pluginartifactId>
            <version>2.6version>
            <executions>
                <execution>
                    <id>copy-resourcesid>
                    <phase>generate-resourcesphase>
                    <goals>
                        <goal>copy-resourcesgoal>
                    goals>
                    <configuration>
                        <outputDirectory>${project.build.directory}/${project.artifactId}outputDirectory>
                        <resources>
                            <resource>
                                <directory>${project.build.directory}/swagger-ui/META-INF/resources/webjars/swagger-ui/2.1.0directory>
                                <filtering>truefiltering>
                            resource>
                        resources>
                    configuration>
                execution>
            executions>
        plugin>

    plugins>
build>

五、web.xml

xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns="http://java.sun.com/xml/ns/javaee"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
         metadata-complete="true" version="3.0">
    
    <context-param>
        <param-name>contextConfigLocationparam-name>
        <param-value>classpath:spring.xmlparam-value>
    context-param>
    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListenerlistener-class>
    listener>

    
    <servlet>
        <servlet-name>cxfservlet-name>
        <servlet-class>org.apache.cxf.transport.servlet.CXFServletservlet-class>
    servlet>
    <servlet-mapping>
        <servlet-name>cxfservlet-name>
        <url-pattern>/ws/*url-pattern>
    servlet-mapping>

web-app>

六、结果访问：

http://localhost:8080/sample-web/index.html?url=http://localhost:8080/sample-web/ws/swagger.json