swagger 在apache CXF 中的使用——JAX-RS Swagger2Feature

The CXF Swagger2Feature allows you to generate Swagger 2.0 documents from JAX-RS service endpoints with a simple configuration.
见：http://cxf.apache.org/docs/swagger2feature.html

JAX-RS Swagger2Feature Demo
=================

The demo shows a basic usage of Swagger 2.0 API documentation with REST based Web Services using
JAX-RS 2.0 (JSR-339). Swagger UI is available at: http://localhost:9000/

Building and running the demo using Maven
---------------------------------------

From the base directory of this sample (i.e., where this README file is
located), the Maven pom.xml file can be used to build and run the demo. 

Using either UNIX or Windows:

  mvn install
  mvn -Pserver  (from one command line window)  

After the service is started, the Swagger API documents in JSON and YAML
are available at

  http://localhost:9000/swagger.json
  http://localhost:9000/swagger.yaml

To view the Swagger document using Swagger-UI, use your Browser to
open the Swagger-UI page at

  http://localhost:9000/api-docs?url=/swagger.json

or

  http://localhost:9000/api-docs?url=/swagger.yaml

or access it from the CXF Services page:

  http://localhost:9000/services
  and follow a Swagger link.

例子在：https://github.com/apache/cxf/blob/master/distribution/src/main/release/samples/jax_rs/description_swagger2/src/main/java/demo/jaxrs/swagger/server/Sample.java

示意代码：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;

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

    public Sample() {
        items = Collections.synchronizedMap(new TreeMap<String, Item>(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();
    }
}