This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/master by this push:
new 9684668 CAMEL-11957: rest-dsl now allows to turn off vendor
extensions in generated swagger doc which may be needed when API tools does not
support vendor extensions if you import the api docs in those tools.
9684668 is described below
commit 9684668357b09c5a6af9d99b4de2c17be1a2a08c
Author: Claus Ibsen <[email protected]>
AuthorDate: Fri Oct 27 15:42:31 2017 +0200
CAMEL-11957: rest-dsl now allows to turn off vendor extensions in generated
swagger doc which may be needed when API tools does not support vendor
extensions if you import the api docs in those tools.
---
camel-core/src/main/docs/rest-dsl.adoc | 36 ++++++++
.../model/rest/RestConfigurationDefinition.java | 29 +++++++
.../org/apache/camel/spi/RestConfiguration.java | 14 +++
.../apache/camel/swagger/RestSwaggerSupport.java | 13 +++
.../org/apache/camel/swagger/SwaggerHelper.java | 35 ++++++++
...estSwaggerReaderDisableVendorExtensionTest.java | 99 ++++++++++++++++++++++
.../RestConfigurationDefinitionProperties.java | 15 ++++
7 files changed, 241 insertions(+)
diff --git a/camel-core/src/main/docs/rest-dsl.adoc
b/camel-core/src/main/docs/rest-dsl.adoc
index d05f0ee..83855fc 100644
--- a/camel-core/src/main/docs/rest-dsl.adoc
+++ b/camel-core/src/main/docs/rest-dsl.adoc
@@ -711,3 +711,39 @@ And in Java DSL
.to("bean:userService?method=updateUser")
----
+==== Vendor Extensions
+
+The generated API documentation includes vendor extensions
(https://swagger.io/specification/#specificationExtensions)
+which document the operations and definitons with additional information.
+
+This information is stored using keys starting with `x-`. However there are
some API tools that does not support parsing
+vendor extensions, and therefore you can turn this off on `RestConfiguration`
via the `apiVendorExtension` option:
+
+[source,java]
+----
+restConfiguration()
+ .component("servlet")
+ .bindingMode(RestBindingMode.json)
+ .dataFormatProperty("prettyPrint", "true")
+ .apiContextPath("api-doc")
+ .apiVendorExtension(false)
+ .apiProperty("api.title", "User API").apiProperty("api.version",
"1.0.0")
+ .apiProperty("cors", "true");
+----
+
+And in XML DSL:
+[source,xml]
+----
+ <restConfiguration component="servlet" bindingMode="json"
+ apiContextPath="api-docs"
+ apiVendorExtension="false">
+
+ <!-- we want json output in pretty mode -->
+ <dataFormatProperty key="prettyPrint" value="true"/>
+
+ <!-- setup swagger api descriptions -->
+ <apiProperty key="api.version" value="1.0.0"/>
+ <apiProperty key="api.title" value="User API"/>
+
+</restConfiguration>
+----
\ No newline at end of file
diff --git
a/camel-core/src/main/java/org/apache/camel/model/rest/RestConfigurationDefinition.java
b/camel-core/src/main/java/org/apache/camel/model/rest/RestConfigurationDefinition.java
index 8acb077..fb9d3d5 100644
---
a/camel-core/src/main/java/org/apache/camel/model/rest/RestConfigurationDefinition.java
+++
b/camel-core/src/main/java/org/apache/camel/model/rest/RestConfigurationDefinition.java
@@ -78,6 +78,9 @@ public class RestConfigurationDefinition {
@XmlAttribute @Metadata(label = "consumer")
private Boolean apiContextListing;
+ @XmlAttribute @Metadata(label = "consumer", defaultValue = "true")
+ private Boolean apiVendorExtension;
+
@XmlAttribute @Metadata(label = "consumer")
private RestHostNameResolver hostNameResolver;
@@ -295,6 +298,19 @@ public class RestConfigurationDefinition {
this.apiContextListing = apiContextListing;
}
+ public Boolean getApiVendorExtension() {
+ return apiVendorExtension;
+ }
+
+ /**
+ * Whether vendor extension is enabled in the Rest APIs. If enabled then
Camel will include additional information
+ * as vendor extension (eg keys starting with x-) such as route ids, class
names etc.
+ * Some API tooling may not support vendor extensions and this option can
then be turned off.
+ */
+ public void setApiVendorExtension(Boolean apiVendorExtension) {
+ this.apiVendorExtension = apiVendorExtension;
+ }
+
public RestHostNameResolver getHostNameResolver() {
return hostNameResolver;
}
@@ -570,6 +586,16 @@ public class RestConfigurationDefinition {
}
/**
+ * Whether vendor extension is enabled in the Rest APIs. If enabled then
Camel will include additional information
+ * as vendor extension (eg keys starting with x-) such as route ids, class
names etc.
+ * Some API tooling may not support vendor extensions and this option can
then be turned off.
+ */
+ public RestConfigurationDefinition apiVendorExtension(boolean
vendorExtension) {
+ setApiVendorExtension(vendorExtension);
+ return this;
+ }
+
+ /**
* Sets a leading context-path the REST services will be using.
* <p/>
* This can be used when using components such as <tt>camel-servlet</tt>
where the deployed web application
@@ -771,6 +797,9 @@ public class RestConfigurationDefinition {
if (apiContextListing != null) {
answer.setApiContextListing(apiContextListing);
}
+ if (apiVendorExtension != null) {
+ answer.setApiVendorExtension(apiVendorExtension);
+ }
if (contextPath != null) {
answer.setContextPath(CamelContextHelper.parseText(context,
contextPath));
}
diff --git
a/camel-core/src/main/java/org/apache/camel/spi/RestConfiguration.java
b/camel-core/src/main/java/org/apache/camel/spi/RestConfiguration.java
index ce9854a..3802c1d 100644
--- a/camel-core/src/main/java/org/apache/camel/spi/RestConfiguration.java
+++ b/camel-core/src/main/java/org/apache/camel/spi/RestConfiguration.java
@@ -50,6 +50,7 @@ public class RestConfiguration {
private String apiContextRouteId;
private String apiContextIdPattern;
private boolean apiContextListing;
+ private boolean apiVendorExtension = true;
private RestHostNameResolver restHostNameResolver =
RestHostNameResolver.allLocalIp;
private RestBindingMode bindingMode = RestBindingMode.off;
private boolean skipBindingOnErrorCode = true;
@@ -286,6 +287,19 @@ public class RestConfiguration {
this.apiContextListing = apiContextListing;
}
+ public boolean isApiVendorExtension() {
+ return apiVendorExtension;
+ }
+
+ /**
+ * Whether vendor extension is enabled in the Rest APIs. If enabled then
Camel will include additional information
+ * as vendor extension (eg keys starting with x-) such as route ids, class
names etc.
+ * Some API tooling may not support vendor extensions and this option can
then be turned off.
+ */
+ public void setApiVendorExtension(boolean apiVendorExtension) {
+ this.apiVendorExtension = apiVendorExtension;
+ }
+
/**
* Gets the resolver to use for resolving hostname
*
diff --git
a/components/camel-swagger-java/src/main/java/org/apache/camel/swagger/RestSwaggerSupport.java
b/components/camel-swagger-java/src/main/java/org/apache/camel/swagger/RestSwaggerSupport.java
index abef77d..7bd53aa 100644
---
a/components/camel-swagger-java/src/main/java/org/apache/camel/swagger/RestSwaggerSupport.java
+++
b/components/camel-swagger-java/src/main/java/org/apache/camel/swagger/RestSwaggerSupport.java
@@ -35,6 +35,9 @@ import io.swagger.jaxrs.config.BeanConfig;
import io.swagger.models.Contact;
import io.swagger.models.Info;
import io.swagger.models.License;
+import io.swagger.models.Model;
+import io.swagger.models.Path;
+import io.swagger.models.Scheme;
import io.swagger.models.Swagger;
import io.swagger.util.Yaml;
import org.apache.camel.Exchange;
@@ -48,6 +51,8 @@ import org.apache.camel.util.EndpointHelper;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
+import static org.apache.camel.swagger.SwaggerHelper.clearVendorExtensions;
+
/**
* A support class for that allows SPI to plugin
* and offer Swagger API service listings as part of the Camel component. This
allows rest-dsl components
@@ -207,6 +212,10 @@ public class RestSwaggerSupport {
// read the rest-dsl into swagger model
Swagger swagger = reader.read(rests, route, swaggerConfig,
contextId, classResolver);
+ if (!configuration.isApiVendorExtension()) {
+ clearVendorExtensions(swagger);
+ }
+
ObjectMapper mapper = new ObjectMapper();
mapper.enable(SerializationFeature.INDENT_OUTPUT);
mapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);
@@ -222,6 +231,10 @@ public class RestSwaggerSupport {
// read the rest-dsl into swagger model
Swagger swagger = reader.read(rests, route, swaggerConfig,
contextId, classResolver);
+ if (!configuration.isApiVendorExtension()) {
+ clearVendorExtensions(swagger);
+ }
+
ObjectMapper mapper = new ObjectMapper();
mapper.enable(SerializationFeature.INDENT_OUTPUT);
mapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);
diff --git
a/components/camel-swagger-java/src/main/java/org/apache/camel/swagger/SwaggerHelper.java
b/components/camel-swagger-java/src/main/java/org/apache/camel/swagger/SwaggerHelper.java
index eb5124a..ccf0f98 100644
---
a/components/camel-swagger-java/src/main/java/org/apache/camel/swagger/SwaggerHelper.java
+++
b/components/camel-swagger-java/src/main/java/org/apache/camel/swagger/SwaggerHelper.java
@@ -16,6 +16,10 @@
*/
package org.apache.camel.swagger;
+import io.swagger.models.Model;
+import io.swagger.models.Operation;
+import io.swagger.models.Path;
+import io.swagger.models.Swagger;
import org.apache.camel.util.FileUtil;
public final class SwaggerHelper {
@@ -34,4 +38,35 @@ public final class SwaggerHelper {
return path2;
}
}
+
+ /**
+ * Clears all the vendor extension on the swagger model. This may be
needed as some API tooling does not support this.
+ */
+ public static void clearVendorExtensions(Swagger swagger) {
+ if (swagger.getVendorExtensions() != null) {
+ swagger.getVendorExtensions().clear();
+ }
+
+ if (swagger.getDefinitions() != null) {
+ for (Model model : swagger.getDefinitions().values()) {
+ if (model.getVendorExtensions() != null) {
+ model.getVendorExtensions().clear();
+ }
+ }
+ }
+
+ if (swagger.getPaths() != null) {
+ for (Path path : swagger.getPaths().values()) {
+ if (path.getVendorExtensions() != null) {
+ path.getVendorExtensions().clear();
+ }
+ for (Operation op : path.getOperations()) {
+ if (op.getVendorExtensions() != null) {
+ op.getVendorExtensions().clear();
+ }
+ }
+ }
+ }
+ }
+
}
diff --git
a/components/camel-swagger-java/src/test/java/org/apache/camel/swagger/RestSwaggerReaderDisableVendorExtensionTest.java
b/components/camel-swagger-java/src/test/java/org/apache/camel/swagger/RestSwaggerReaderDisableVendorExtensionTest.java
new file mode 100644
index 0000000..41c88ff
--- /dev/null
+++
b/components/camel-swagger-java/src/test/java/org/apache/camel/swagger/RestSwaggerReaderDisableVendorExtensionTest.java
@@ -0,0 +1,99 @@
+/**
+ * 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 org.apache.camel.swagger;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.SerializationFeature;
+import io.swagger.jaxrs.config.BeanConfig;
+import io.swagger.models.Swagger;
+import org.apache.camel.builder.RouteBuilder;
+import org.apache.camel.impl.DefaultClassResolver;
+import org.apache.camel.impl.JndiRegistry;
+import org.apache.camel.model.rest.RestParamType;
+import org.apache.camel.test.junit4.CamelTestSupport;
+import org.junit.Test;
+
+import static org.apache.camel.swagger.SwaggerHelper.clearVendorExtensions;
+
+public class RestSwaggerReaderDisableVendorExtensionTest extends
CamelTestSupport {
+
+ @Override
+ protected JndiRegistry createRegistry() throws Exception {
+ JndiRegistry jndi = super.createRegistry();
+ jndi.bind("dummy-rest", new DummyRestConsumerFactory());
+ return jndi;
+ }
+
+ @Override
+ protected RouteBuilder createRouteBuilder() throws Exception {
+ return new RouteBuilder() {
+ @Override
+ public void configure() throws Exception {
+ // this user REST service is json only
+ rest("/user").tag("dude").description("User rest service")
+ .consumes("application/json").produces("application/json")
+
+ .get("/{id}").description("Find user by
id").outType(User.class)
+ .responseMessage().message("The user
returned").endResponseMessage()
+
.param().name("id").type(RestParamType.path).description("The id of the user to
get").dataType("integer").endParam()
+ .to("bean:userService?method=getUser(${header.id})")
+
+ .put().description("Updates or create a
user").type(User.class)
+
.param().name("body").type(RestParamType.body).description("The user to update
or create").endParam()
+ .to("bean:userService?method=updateUser")
+
+ .get("/findAll").description("Find all
users").outTypeList(User.class)
+ .responseMessage().message("All the found
users").endResponseMessage()
+ .to("bean:userService?method=listUsers");
+ }
+ };
+ }
+
+ @Test
+ public void testDisableVendorExtension() throws Exception {
+ BeanConfig config = new BeanConfig();
+ config.setHost("localhost:8080");
+ config.setSchemes(new String[]{"http"});
+ config.setBasePath("/api");
+ config.setTitle("Camel User store");
+ config.setLicense("Apache 2.0");
+
config.setLicenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html";);
+ RestSwaggerReader reader = new RestSwaggerReader();
+
+ Swagger swagger = reader.read(context.getRestDefinitions(), null,
config, context.getName(), new DefaultClassResolver());
+ assertNotNull(swagger);
+
+ clearVendorExtensions(swagger);
+
+ ObjectMapper mapper = new ObjectMapper();
+ mapper.enable(SerializationFeature.INDENT_OUTPUT);
+ mapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);
+ String json = mapper.writeValueAsString(swagger);
+
+ log.info(json);
+
+ assertTrue(json.contains("\"host\" : \"localhost:8080\""));
+ assertTrue(json.contains("\"description\" : \"The user returned\""));
+ assertTrue(json.contains("\"$ref\" : \"#/definitions/User\""));
+ assertFalse(json.contains("\"enum\""));
+ assertFalse(json.contains("\"x-camelContextId\" : \"camel-1\""));
+ assertFalse(json.contains("\"x-routeId\" : \"route1\""));
+ context.stop();
+ }
+
+}
diff --git
a/platforms/spring-boot/components-starter/camel-core-starter/src/main/java/org/apache/camel/model/rest/springboot/RestConfigurationDefinitionProperties.java
b/platforms/spring-boot/components-starter/camel-core-starter/src/main/java/org/apache/camel/model/rest/springboot/RestConfigurationDefinitionProperties.java
index f490daa..ad3dc2d 100644
---
a/platforms/spring-boot/components-starter/camel-core-starter/src/main/java/org/apache/camel/model/rest/springboot/RestConfigurationDefinitionProperties.java
+++
b/platforms/spring-boot/components-starter/camel-core-starter/src/main/java/org/apache/camel/model/rest/springboot/RestConfigurationDefinitionProperties.java
@@ -115,6 +115,13 @@ public class RestConfigurationDefinitionProperties {
*/
private Boolean apiContextListing = false;
/**
+ * Whether vendor extension is enabled in the Rest APIs. If enabled then
+ * Camel will include additional information as vendor extension (eg keys
+ * starting with x-) such as route ids class names etc. Some API tooling
may
+ * not support vendor extensions and this option can then be turned off.
+ */
+ private Boolean apiVendorExtension = true;
+ /**
* If no hostname has been explicit configured then this resolver is used
to
* compute the hostname the REST service will be using.
*/
@@ -286,6 +293,14 @@ public class RestConfigurationDefinitionProperties {
this.apiContextListing = apiContextListing;
}
+ public Boolean getApiVendorExtension() {
+ return apiVendorExtension;
+ }
+
+ public void setApiVendorExtension(Boolean apiVendorExtension) {
+ this.apiVendorExtension = apiVendorExtension;
+ }
+
public RestHostNameResolver getHostNameResolver() {
return hostNameResolver;
}
--
To stop receiving notification emails like this one, please contact
['"[email protected]" <[email protected]>'].
