You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by da...@apache.org on 2017/10/27 14:52:41 UTC
[camel] branch master updated: CAMEL-11958: rest-dsl - Disable
vendor extension by default in generated api doc as not all 3rd party api
gateways/tooling support this.
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 f095b89 CAMEL-11958: rest-dsl - Disable vendor extension by default in generated api doc as not all 3rd party api gateways/tooling support this.
f095b89 is described below
commit f095b89848d28d3b116c4cffa10f88d61d21de65
Author: Claus Ibsen <cl...@gmail.com>
AuthorDate: Fri Oct 27 16:52:02 2017 +0200
CAMEL-11958: rest-dsl - Disable vendor extension by default in generated api doc as not all 3rd party api gateways/tooling support this.
---
camel-core/src/main/docs/rest-dsl.adoc | 17 +++++++++++------
.../camel/model/rest/RestConfigurationDefinition.java | 4 ++--
.../java/org/apache/camel/spi/RestConfiguration.java | 4 ++--
...=> RestSwaggerReaderEnableVendorExtensionTest.java} | 18 ++++++++++--------
.../RestConfigurationDefinitionProperties.java | 7 ++++---
5 files changed, 29 insertions(+), 21 deletions(-)
diff --git a/camel-core/src/main/docs/rest-dsl.adoc b/camel-core/src/main/docs/rest-dsl.adoc
index 83855fc..fc5c201 100644
--- a/camel-core/src/main/docs/rest-dsl.adoc
+++ b/camel-core/src/main/docs/rest-dsl.adoc
@@ -713,11 +713,16 @@ And in Java DSL
==== Vendor Extensions
-The generated API documentation includes vendor extensions (https://swagger.io/specification/#specificationExtensions)
-which document the operations and definitons with additional information.
+The generated API documentation can be configured to include vendor extensions (https://swagger.io/specification/#specificationExtensions)
+which document the operations and definitions with additional information, such as class name of model classes, camel context id and route id's.
+This information can aid developers and during trouble shooting. However at production usage you may wish to not have this turned
+on to avoid leaking implementation details into your API docs.
-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:
+The vendor extension information is stored in the API documentation with keys starting with `x-`.
+
+NOTE: Not all 3rd party API gateways and tools supports vendor-extensions when importing your API docs.
+
+The vendor extensions can be turned on `RestConfiguration` via the `apiVendorExtension` option:
[source,java]
----
@@ -726,7 +731,7 @@ restConfiguration()
.bindingMode(RestBindingMode.json)
.dataFormatProperty("prettyPrint", "true")
.apiContextPath("api-doc")
- .apiVendorExtension(false)
+ .apiVendorExtension(true)
.apiProperty("api.title", "User API").apiProperty("api.version", "1.0.0")
.apiProperty("cors", "true");
----
@@ -736,7 +741,7 @@ And in XML DSL:
----
<restConfiguration component="servlet" bindingMode="json"
apiContextPath="api-docs"
- apiVendorExtension="false">
+ apiVendorExtension="true">
<!-- we want json output in pretty mode -->
<dataFormatProperty key="prettyPrint" value="true"/>
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 fb9d3d5..0444f6b 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,7 +78,7 @@ public class RestConfigurationDefinition {
@XmlAttribute @Metadata(label = "consumer")
private Boolean apiContextListing;
- @XmlAttribute @Metadata(label = "consumer", defaultValue = "true")
+ @XmlAttribute @Metadata(label = "consumer")
private Boolean apiVendorExtension;
@XmlAttribute @Metadata(label = "consumer")
@@ -305,7 +305,7 @@ 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.
+ * Not all 3rd party API gateways and tools supports vendor-extensions when importing your API docs.
*/
public void setApiVendorExtension(Boolean apiVendorExtension) {
this.apiVendorExtension = apiVendorExtension;
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 3802c1d..6f85d95 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,7 +50,7 @@ public class RestConfiguration {
private String apiContextRouteId;
private String apiContextIdPattern;
private boolean apiContextListing;
- private boolean apiVendorExtension = true;
+ private boolean apiVendorExtension;
private RestHostNameResolver restHostNameResolver = RestHostNameResolver.allLocalIp;
private RestBindingMode bindingMode = RestBindingMode.off;
private boolean skipBindingOnErrorCode = true;
@@ -294,7 +294,7 @@ public class RestConfiguration {
/**
* 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.
+ * Not all 3rd party API gateways and tools supports vendor-extensions when importing your API docs.
*/
public void setApiVendorExtension(boolean apiVendorExtension) {
this.apiVendorExtension = apiVendorExtension;
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/RestSwaggerReaderEnableVendorExtensionTest.java
similarity index 88%
rename from components/camel-swagger-java/src/test/java/org/apache/camel/swagger/RestSwaggerReaderDisableVendorExtensionTest.java
rename to components/camel-swagger-java/src/test/java/org/apache/camel/swagger/RestSwaggerReaderEnableVendorExtensionTest.java
index 41c88ff..ac83805 100644
--- 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/RestSwaggerReaderEnableVendorExtensionTest.java
@@ -28,9 +28,7 @@ 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 {
+public class RestSwaggerReaderEnableVendorExtensionTest extends CamelTestSupport {
@Override
protected JndiRegistry createRegistry() throws Exception {
@@ -44,6 +42,9 @@ public class RestSwaggerReaderDisableVendorExtensionTest extends CamelTestSuppor
return new RouteBuilder() {
@Override
public void configure() throws Exception {
+ // enable vendor extensions
+ restConfiguration().apiVendorExtension(true);
+
// this user REST service is json only
rest("/user").tag("dude").description("User rest service")
.consumes("application/json").produces("application/json")
@@ -65,7 +66,7 @@ public class RestSwaggerReaderDisableVendorExtensionTest extends CamelTestSuppor
}
@Test
- public void testDisableVendorExtension() throws Exception {
+ public void testEnableVendorExtension() throws Exception {
BeanConfig config = new BeanConfig();
config.setHost("localhost:8080");
config.setSchemes(new String[]{"http"});
@@ -78,8 +79,6 @@ public class RestSwaggerReaderDisableVendorExtensionTest extends CamelTestSuppor
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);
@@ -87,12 +86,15 @@ public class RestSwaggerReaderDisableVendorExtensionTest extends CamelTestSuppor
log.info(json);
+ String camelId = context.getName();
+ String routeId = context.getRouteDefinitions().get(0).getId();
+
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\""));
+ assertTrue(json.contains("\"x-camelContextId\" : \"" + camelId + "\""));
+ assertTrue(json.contains("\"x-routeId\" : \"" + routeId + "\""));
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 ad3dc2d..b6297b1 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
@@ -117,10 +117,11 @@ public class RestConfigurationDefinitionProperties {
/**
* 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.
+ * starting with x-) such as route ids class names etc. Not all 3rd party
+ * API gateways and tools supports vendor-extensions when importing your API
+ * docs.
*/
- private Boolean apiVendorExtension = true;
+ private Boolean apiVendorExtension = false;
/**
* If no hostname has been explicit configured then this resolver is used to
* compute the hostname the REST service will be using.
--
To stop receiving notification emails like this one, please contact
['"commits@camel.apache.org" <co...@camel.apache.org>'].