You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cxf.apache.org by re...@apache.org on 2018/05/26 20:39:07 UTC
[cxf] branch master updated: Adding OpenAPI v3.0 sample project for
WAR-based deployment (using web.xml)
This is an automated email from the ASF dual-hosted git repository.
reta pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cxf.git
The following commit(s) were added to refs/heads/master by this push:
new 4006ec8 Adding OpenAPI v3.0 sample project for WAR-based deployment (using web.xml)
4006ec8 is described below
commit 4006ec85a5da1b3192d145b74cdfbd1d14e8aa0c
Author: reta <dr...@gmail.com>
AuthorDate: Sat May 26 16:38:50 2018 -0400
Adding OpenAPI v3.0 sample project for WAR-based deployment (using web.xml)
---
.../jax_rs/description_openapi_v3_web/README.txt | 34 +++++
.../jax_rs/description_openapi_v3_web/pom.xml | 85 +++++++++++
.../demo/jaxrs/openapi/server/ApiOriginFilter.java | 45 ++++++
.../main/java/demo/jaxrs/openapi/server/Item.java | 49 +++++++
.../java/demo/jaxrs/openapi/server/Sample.java | 161 +++++++++++++++++++++
.../src/main/resources/openapi-configuration.json | 30 ++++
.../src/main/webapp/WEB-INF/web.xml | 50 +++++++
distribution/src/main/release/samples/pom.xml | 1 +
8 files changed, 455 insertions(+)
diff --git a/distribution/src/main/release/samples/jax_rs/description_openapi_v3_web/README.txt b/distribution/src/main/release/samples/jax_rs/description_openapi_v3_web/README.txt
new file mode 100644
index 0000000..e26f5a8
--- /dev/null
+++ b/distribution/src/main/release/samples/jax_rs/description_openapi_v3_web/README.txt
@@ -0,0 +1,34 @@
+JAX-RS OpenApiFeature Demo using WebApp
+=================
+
+The demo shows a basic usage of OpenAPI v3.0 documentation with REST based Web Services using
+JAX-RS 2.0 (JSR-339). In this demo, the OpenApiFeature is configured through web.xml file. The
+sample also demonstrates usage of the openapi-configuration.json configuration file to publish
+API metadata and servers / base path to use.
+
+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 jetty:run-war
+
+The sample JAX-RS endpoint becomes available after the service has started.
+OpenAPI v3.0 documents in JSON and YAML are available at
+
+ http://localhost:9000/app/openapi.json
+ http://localhost:9000/app/openapi.yaml
+
+To view the OpenAPI document using Swagger-UI, use your Browser to
+open the Swagger-UI page at
+
+ http://localhost:9000/app/api-docs?url=/app/openapi.json
+
+To remove the target dir, run mvn clean".
+
+
+
diff --git a/distribution/src/main/release/samples/jax_rs/description_openapi_v3_web/pom.xml b/distribution/src/main/release/samples/jax_rs/description_openapi_v3_web/pom.xml
new file mode 100644
index 0000000..54737c5
--- /dev/null
+++ b/distribution/src/main/release/samples/jax_rs/description_openapi_v3_web/pom.xml
@@ -0,0 +1,85 @@
+<?xml version="1.0"?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+ <artifactId>jax_rs_description_openapi_v3_web</artifactId>
+ <packaging>war</packaging>
+ <name>JAX-RS Open API 3.0 Demo</name>
+ <description>JAX-RS Open API 3.0 Basic Demo using Tomcat and WAR-based deployment</description>
+ <parent>
+ <groupId>org.apache.cxf.samples</groupId>
+ <artifactId>cxf-samples</artifactId>
+ <version>3.2.5-SNAPSHOT</version>
+ <relativePath>../..</relativePath>
+ </parent>
+
+ <properties>
+ <cxf.version>${project.version}</cxf.version>
+ </properties>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.eclipse.jetty</groupId>
+ <artifactId>jetty-maven-plugin</artifactId>
+ <version>9.4.6.v20170531</version>
+ <configuration>
+ <webApp>
+ <contextPath>/</contextPath>
+ </webApp>
+ <httpConnector>
+ <port>9000</port>
+ </httpConnector>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.webjars</groupId>
+ <artifactId>swagger-ui</artifactId>
+ <version>3.13.6</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.cxf</groupId>
+ <artifactId>cxf-rt-transports-http</artifactId>
+ <version>3.2.5-SNAPSHOT</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.cxf</groupId>
+ <artifactId>cxf-rt-frontend-jaxrs</artifactId>
+ <version>3.2.5-SNAPSHOT</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.cxf</groupId>
+ <artifactId>cxf-rt-rs-service-description-openapi-v3</artifactId>
+ <version>3.2.5-SNAPSHOT</version>
+ </dependency>
+ <dependency>
+ <groupId>javax.ws.rs</groupId>
+ <artifactId>javax.ws.rs-api</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>com.fasterxml.jackson.jaxrs</groupId>
+ <artifactId>jackson-jaxrs-json-provider</artifactId>
+ </dependency>
+ </dependencies>
+</project>
diff --git a/distribution/src/main/release/samples/jax_rs/description_openapi_v3_web/src/main/java/demo/jaxrs/openapi/server/ApiOriginFilter.java b/distribution/src/main/release/samples/jax_rs/description_openapi_v3_web/src/main/java/demo/jaxrs/openapi/server/ApiOriginFilter.java
new file mode 100644
index 0000000..e970d0a
--- /dev/null
+++ b/distribution/src/main/release/samples/jax_rs/description_openapi_v3_web/src/main/java/demo/jaxrs/openapi/server/ApiOriginFilter.java
@@ -0,0 +1,45 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package demo.jaxrs.openapi.server;
+
+import java.io.IOException;
+
+import javax.ws.rs.container.ContainerRequestContext;
+import javax.ws.rs.container.ContainerResponseContext;
+import javax.ws.rs.container.ContainerResponseFilter;
+import javax.ws.rs.core.MultivaluedMap;
+
+/**
+ * This is a simple optional CORS filter used for this demo to make the resources accessible
+ * from other origins. You may omit using this filter or use CXF's advanced CORS filter
+ * org.apache.cxf.rs.security.cors.CrossOriginResourceSharingFilter
+ * included in cxf-rt-rs-security-cors if you need a more comprehensive accessibility rules.
+ */
+public class ApiOriginFilter implements ContainerResponseFilter {
+
+ @Override
+ public void filter(ContainerRequestContext requestContext, ContainerResponseContext responseContext)
+ throws IOException {
+ MultivaluedMap<String, Object> headers = responseContext.getHeaders();
+ headers.add("Access-Control-Allow-Origin", "*");
+ headers.add("Access-Control-Allow-Methods", "GET, POST, DELETE, PUT");
+ headers.add("Access-Control-Allow-Headers", "Content-Type");
+ }
+}
diff --git a/distribution/src/main/release/samples/jax_rs/description_openapi_v3_web/src/main/java/demo/jaxrs/openapi/server/Item.java b/distribution/src/main/release/samples/jax_rs/description_openapi_v3_web/src/main/java/demo/jaxrs/openapi/server/Item.java
new file mode 100644
index 0000000..7a32208
--- /dev/null
+++ b/distribution/src/main/release/samples/jax_rs/description_openapi_v3_web/src/main/java/demo/jaxrs/openapi/server/Item.java
@@ -0,0 +1,49 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package demo.jaxrs.openapi.server;
+
+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;
+ }
+}
diff --git a/distribution/src/main/release/samples/jax_rs/description_openapi_v3_web/src/main/java/demo/jaxrs/openapi/server/Sample.java b/distribution/src/main/release/samples/jax_rs/description_openapi_v3_web/src/main/java/demo/jaxrs/openapi/server/Sample.java
new file mode 100644
index 0000000..f07ee28
--- /dev/null
+++ b/distribution/src/main/release/samples/jax_rs/description_openapi_v3_web/src/main/java/demo/jaxrs/openapi/server/Sample.java
@@ -0,0 +1,161 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package demo.jaxrs.openapi.server;
+
+import java.util.Collections;
+import java.util.Map;
+import java.util.TreeMap;
+
+import javax.ws.rs.Consumes;
+import javax.ws.rs.DELETE;
+import javax.ws.rs.DefaultValue;
+import javax.ws.rs.FormParam;
+import javax.ws.rs.GET;
+import javax.ws.rs.HeaderParam;
+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.QueryParam;
+import javax.ws.rs.core.Context;
+import javax.ws.rs.core.MediaType;
+import javax.ws.rs.core.Response;
+import javax.ws.rs.core.Response.Status;
+import javax.ws.rs.core.UriInfo;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.enums.ParameterIn;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+
+@Path("/sample")
+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
+ @Operation(
+ summary = "Get all items",
+ description = "Get operation with Response and @Default value",
+ responses = {
+ @ApiResponse(
+ content = @Content(array = @ArraySchema(schema = @Schema(implementation = Item.class))),
+ responseCode = "200"
+ )
+ }
+ )
+ public Response getItems(@Parameter(required = true) @QueryParam("page") @DefaultValue("1") int page) {
+ return Response.ok(items.values()).build();
+ }
+
+ @Produces({ MediaType.APPLICATION_JSON })
+ @Path("/{name}")
+ @GET
+ @Operation(
+ summary = "Get item by name",
+ description = "Get operation with type and headers",
+ responses = {
+ @ApiResponse(content = @Content(schema = @Schema(implementation = Item.class)), responseCode = "200"),
+ @ApiResponse(responseCode = "404")
+ }
+ )
+ public Response getItem(
+ @Parameter(required = true) @HeaderParam("Accept-Language") final String language,
+ @Parameter(required = true) @PathParam("name") String name) {
+ return items.containsKey(name)
+ ? Response.ok().entity(items.get(name)).build()
+ : Response.status(Status.NOT_FOUND).build();
+ }
+
+ @Consumes({ MediaType.APPLICATION_JSON })
+ @POST
+ @Operation(
+ summary = "Create new item",
+ description = "Post operation with entity in a body",
+ responses = {
+ @ApiResponse(
+ content = @Content(
+ schema = @Schema(implementation = Item.class),
+ mediaType = MediaType.APPLICATION_JSON
+ ),
+ headers = @Header(name = "Location"),
+ responseCode = "201"
+ )
+ }
+ )
+ public Response createItem(
+ @Context final UriInfo uriInfo,
+ @Parameter(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
+ @Operation(
+ summary = "Update an existing new item",
+ description = "Put operation with form parameter",
+ responses = {
+ @ApiResponse(
+ content = @Content(schema = @Schema(implementation = Item.class)),
+ responseCode = "200"
+ )
+ }
+ )
+ public Item updateItem(
+ @Parameter(required = true) @PathParam("name") String name,
+ @Parameter(required = true) @FormParam("value") String value) {
+ Item item = new Item(name, value);
+ items.put(name, item);
+ return item;
+ }
+
+ @Path("/{name}")
+ @DELETE
+ @Operation(
+ summary = "Delete an existing new item",
+ description = "Delete operation with implicit header",
+ responses = @ApiResponse(responseCode = "204")
+ )
+ @Parameter(
+ name = "Accept-Language",
+ description = "language",
+ required = true,
+ schema = @Schema(implementation = String.class),
+ in = ParameterIn.HEADER
+ )
+ public void delete(@Parameter(required = true) @PathParam("name") String name) {
+ items.remove(name);
+ }
+}
diff --git a/distribution/src/main/release/samples/jax_rs/description_openapi_v3_web/src/main/resources/openapi-configuration.json b/distribution/src/main/release/samples/jax_rs/description_openapi_v3_web/src/main/resources/openapi-configuration.json
new file mode 100644
index 0000000..f7a975d
--- /dev/null
+++ b/distribution/src/main/release/samples/jax_rs/description_openapi_v3_web/src/main/resources/openapi-configuration.json
@@ -0,0 +1,30 @@
+{
+ "resourcePackages": [
+ "demo.jaxrs.openapi.server"
+ ],
+ "prettyPrint": true,
+ "cacheTTL": 0,
+ "openAPI": {
+ "info": {
+ "version": "1.0.0",
+ "title": "Sample API",
+ "description": "A sample API",
+ "contact": {
+ "email": "cxf-dev@apache.org"
+ },
+ "license": {
+ "name": "Apache 2.0",
+ "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
+ }
+ },
+ "servers": [
+ {
+ "url": "/app",
+ "description": "The sample API server"
+ }
+ ]
+ },
+ "userDefinedOptions": {
+ "support.swagger.ui": true
+ }
+}
diff --git a/distribution/src/main/release/samples/jax_rs/description_openapi_v3_web/src/main/webapp/WEB-INF/web.xml b/distribution/src/main/release/samples/jax_rs/description_openapi_v3_web/src/main/webapp/WEB-INF/web.xml
new file mode 100644
index 0000000..4ea7430
--- /dev/null
+++ b/distribution/src/main/release/samples/jax_rs/description_openapi_v3_web/src/main/webapp/WEB-INF/web.xml
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" version="3.0"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
+
+ <display-name>CXF OpenAPI v3.0 Sample</display-name>
+ <servlet>
+ <display-name>CXF Service Servlet</display-name>
+ <servlet-name>CXFServiceServlet</servlet-name>
+ <servlet-class>org.apache.cxf.jaxrs.servlet.CXFNonSpringJaxrsServlet</servlet-class>
+ <load-on-startup>1</load-on-startup>
+ <init-param>
+ <param-name>jaxrs.serviceClasses</param-name>
+ <param-value>demo.jaxrs.openapi.server.Sample</param-value>
+ </init-param>
+ <init-param>
+ <param-name>jaxrs.features</param-name>
+ <param-value>org.apache.cxf.jaxrs.openapi.OpenApiFeature</param-value>
+ </init-param>
+ <init-param>
+ <param-name>jaxrs.providers</param-name>
+ <param-value>
+ org.apache.cxf.jaxrs.provider.MultipartProvider,
+ com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider,
+ demo.jaxrs.openapi.server.ApiOriginFilter
+ </param-value>
+ </init-param>
+ </servlet>
+ <servlet-mapping>
+ <servlet-name>CXFServiceServlet</servlet-name>
+ <url-pattern>/app/*</url-pattern>
+ </servlet-mapping>
+</web-app>
diff --git a/distribution/src/main/release/samples/pom.xml b/distribution/src/main/release/samples/pom.xml
index e703821..ec37ce2 100644
--- a/distribution/src/main/release/samples/pom.xml
+++ b/distribution/src/main/release/samples/pom.xml
@@ -72,6 +72,7 @@
<module>jax_rs/content_negotiation</module>
<module>jax_rs/description_openapi_v3</module>
<module>jax_rs/description_openapi_v3_osgi</module>
+ <module>jax_rs/description_openapi_v3_web</module>
<module>jax_rs/description_swagger2</module>
<module>jax_rs/description_swagger2_osgi</module>
<module>jax_rs/description_swagger2_spring</module>
--
To stop receiving notification emails like this one, please contact
reta@apache.org.