54.2. Karaf 実装
ここでは、REST サービスが JAR ファイルで定義され、Fuse on Karaf コンテナーにデプロイされる OpenApiFeature を使用する方法を説明します。
54.2.1. クイックスタートの例
Fuse Software Downloads ページから Red Hat Fuse quickstarts をダウンロードできます。
Quickstart zip ファイルには、CXF を使用して RESTful (JAX-RS) Web サービスを作成する方法と、OpenAPI を有効にして JAX-RS エンドポイントにアノテーションを付ける方法を実証するクイックスタートの /cxf/rest/ ディレクトリーが含まれています。
54.2.2. OpenAPI の有効化
OpenAPI を有効にするには、以を行います。
CXF クラス (
org.apache.cxf.jaxrs.openapi.OpenApiFeature) を<jaxrs:server>定義に追加して CXF サービスを定義する XML ファイルを変更します。例は、例 55.4: XML ファイル を参照してください。
REST リソースクラスで以下を行います。
サービスで必要な各アノテーションの OpenAPI アノテーションをインポートします。
import io.swagger.annotations.*
ここで、* は
Api、ApiOperation、ApiParam、ApiResponse、ApiResponsesなどです。詳細は、
https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.Xを参照してください。例は、例 55.5: リソースクラスの例 を参照してください。
-
OpenAPI アノテーションを JAX-RS でアノテーションが付けられたエンドポイント (
@PATH、@PUT、@POST、@GET、@Produces、@Consumes、@DELETE、@PathParamなど) に追加します。
例は、例 55.5: リソースクラスの例 を参照してください。
例 55.4: XML ファイル
<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">
<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="org.apache.cxf.jaxrs.openapi.OpenApiFeature">
<property name="title" value="Fuse:CXF:Quickstarts - Customer Service" />
<property name="description" value="Sample REST-based Customer Service" />
<property name="version" value="${project.version}" />
</bean>
</jaxrs:features>
</jaxrs:server>
<cxf:bus>
<cxf:features>
<cxf:logging />
</cxf:features>
<cxf:properties>
<entry key="skip.default.json.provider.registration" value="true" />
</cxf:properties>
</cxf:bus>
<bean id="customerSvc" class="org.jboss.fuse.quickstarts.cxf.rest.CustomerService"/>
</blueprint>
例 55.5: リソースクラスの例
.
.
.
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.Context;
import javax.ws.rs.core.Response;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
.
.
.
@Path("/customerservice/")
@Api(value = "/customerservice", description = "Operations about customerservice")
public class CustomerService {
private static final Logger LOG =
LoggerFactory.getLogger(CustomerService.class);
private MessageContext jaxrsContext;
private long currentId = 123;
private Map<Long, Customer> customers = new HashMap<>();
private Map<Long, Order> orders = new HashMap<>();
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);
return customers.get(idNumber);
}
@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);
Response r;
if (c != null) {
r = Response.ok().build();
customers.remove(idNumber);
} else {
r = Response.notModified().build();
}
return r;
}
.
.
.
}
