You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by zr...@apache.org on 2019/05/07 11:53:27 UTC
[camel] 01/03: Improve docs a bit for camel-rest-swagger when
loading swagger spec from https. Also fixed so catching wider exception in
fallback to let swagger attempt to load.
This is an automated email from the ASF dual-hosted git repository.
zregvart pushed a commit to branch camel-2.x
in repository https://gitbox.apache.org/repos/asf/camel.git
commit c4fb25cfecd2d7b715710d7fcc671ce9e14260e1
Author: Claus Ibsen <cl...@gmail.com>
AuthorDate: Tue Feb 12 09:43:24 2019 +0100
Improve docs a bit for camel-rest-swagger when loading swagger spec from https. Also fixed so catching wider exception in fallback to let swagger attempt to load.
(cherry picked from commit 9a0628caf438ed5bd5f688392e97c8e3d8a9ed46)
---
.../src/main/docs/rest-swagger-component.adoc | 12 ++++++------
.../component/rest/swagger/RestSwaggerComponent.java | 12 ++++++------
.../component/rest/swagger/RestSwaggerEndpoint.java | 16 ++++++++++------
.../camel/component/rest/swagger/RestSwaggerHelper.java | 2 +-
.../springboot/RestSwaggerComponentConfiguration.java | 12 ++++++------
5 files changed, 29 insertions(+), 25 deletions(-)
diff --git a/components/camel-rest-swagger/src/main/docs/rest-swagger-component.adoc b/components/camel-rest-swagger/src/main/docs/rest-swagger-component.adoc
index 8e211a8..08baabe 100644
--- a/components/camel-rest-swagger/src/main/docs/rest-swagger-component.adoc
+++ b/components/camel-rest-swagger/src/main/docs/rest-swagger-component.adoc
@@ -92,11 +92,11 @@ The REST Swagger component supports 9 options, which are listed below.
|===
| Name | Description | Default | Type
| *basePath* (producer) | API basePath, for example /v2. Default is unset, if set overrides the value present in Swagger specification. | | String
-| *componentName* (producer) | Name of the Camel component that will perform the requests. The compnent must be present in Camel registry and it must implement RestProducerFactory service provider interface. If not set CLASSPATH is searched for single component that implements RestProducerFactory SPI. Can be overriden in endpoint configuration. | | String
-| *consumes* (producer) | What payload type this component capable of consuming. Could be one type, like application/json or multiple types as application/json, application/xml; q=0.5 according to the RFC7231. This equates to the value of Accept HTTP header. If set overrides any value found in the Swagger specification. Can be overriden in endpoint configuration | | String
-| *host* (producer) | Scheme hostname and port to direct the HTTP requests to in the form of https://hostname:port. Can be configured at the endpoint, component or in the correspoding REST configuration in the Camel Context. If you give this component a name (e.g. petstore) that REST configuration is consulted first, rest-swagger next, and global configuration last. If set overrides any value found in the Swagger specification, RestConfiguration. Can be overriden in endpoint configuratio [...]
-| *produces* (producer) | What payload type this component is producing. For example application/json according to the RFC7231. This equates to the value of Content-Type HTTP header. If set overrides any value present in the Swagger specification. Can be overriden in endpoint configuration. | | String
-| *specificationUri* (producer) | Path to the Swagger specification file. The scheme, host base path are taken from this specification, but these can be overriden with properties on the component or endpoint level. If not given the component tries to load swagger.json resource. Note that the host defined on the component and endpoint of this Component should contain the scheme, hostname and optionally the port in the URI syntax (i.e. https://api.example.com:8080). Can be overriden in end [...]
+| *componentName* (producer) | Name of the Camel component that will perform the requests. The component must be present in Camel registry and it must implement RestProducerFactory service provider interface. If not set CLASSPATH is searched for single component that implements RestProducerFactory SPI. Can be overridden in endpoint configuration. | | String
+| *consumes* (producer) | What payload type this component capable of consuming. Could be one type, like application/json or multiple types as application/json, application/xml; q=0.5 according to the RFC7231. This equates to the value of Accept HTTP header. If set overrides any value found in the Swagger specification. Can be overridden in endpoint configuration | | String
+| *host* (producer) | Scheme hostname and port to direct the HTTP requests to in the form of https://hostname:port. Can be configured at the endpoint, component or in the correspoding REST configuration in the Camel Context. If you give this component a name (e.g. petstore) that REST configuration is consulted first, rest-swagger next, and global configuration last. If set overrides any value found in the Swagger specification, RestConfiguration. Can be overridden in endpoint configurati [...]
+| *produces* (producer) | What payload type this component is producing. For example application/json according to the RFC7231. This equates to the value of Content-Type HTTP header. If set overrides any value present in the Swagger specification. Can be overridden in endpoint configuration. | | String
+| *specificationUri* (producer) | Path to the Swagger specification file. The scheme, host base path are taken from this specification, but these can be overriden with properties on the component or endpoint level. If not given the component tries to load swagger.json resource. Note that the host defined on the component and endpoint of this Component should contain the scheme, hostname and optionally the port in the URI syntax (i.e. https://api.example.com:8080). Can be overridden in en [...]
| *sslContextParameters* (security) | Customize TLS parameters used by the component. If not set defaults to the TLS parameters set in the Camel context | | SSLContextParameters
| *useGlobalSslContext Parameters* (security) | Enable usage of global SSL context parameters. | false | boolean
| *resolveProperty Placeholders* (advanced) | Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders. | true | boolean
@@ -118,7 +118,7 @@ with the following path and query parameters:
[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
-| *specificationUri* | Path to the Swagger specification file. The scheme, host base path are taken from this specification, but these can be overriden with properties on the component or endpoint level. If not given the component tries to load swagger.json resource. Note that the host defined on the component and endpoint of this Component should contain the scheme, hostname and optionally the port in the URI syntax (i.e. https://api.example.com:8080). Overrides component configuration. [...]
+| *specificationUri* | Path to the Swagger specification file. The scheme, host base path are taken from this specification, but these can be overridden with properties on the component or endpoint level. If not given the component tries to load swagger.json resource from the classpath. Note that the host defined on the component and endpoint of this Component should contain the scheme, hostname and optionally the port in the URI syntax (i.e. http://api.example.com:8080). Overrides compo [...]
| *operationId* | *Required* ID of the operation from the Swagger specification. | | String
|===
diff --git a/components/camel-rest-swagger/src/main/java/org/apache/camel/component/rest/swagger/RestSwaggerComponent.java b/components/camel-rest-swagger/src/main/java/org/apache/camel/component/rest/swagger/RestSwaggerComponent.java
index 89a5e1e..9835310 100644
--- a/components/camel-rest-swagger/src/main/java/org/apache/camel/component/rest/swagger/RestSwaggerComponent.java
+++ b/components/camel-rest-swagger/src/main/java/org/apache/camel/component/rest/swagger/RestSwaggerComponent.java
@@ -88,9 +88,9 @@ public final class RestSwaggerComponent extends DefaultComponent implements SSLC
defaultValue = "", label = "producer", required = "false")
private String basePath = "";
- @Metadata(description = "Name of the Camel component that will perform the requests. The compnent must be present"
+ @Metadata(description = "Name of the Camel component that will perform the requests. The component must be present"
+ " in Camel registry and it must implement RestProducerFactory service provider interface. If not set"
- + " CLASSPATH is searched for single component that implements RestProducerFactory SPI. Can be overriden in"
+ + " CLASSPATH is searched for single component that implements RestProducerFactory SPI. Can be overridden in"
+ " endpoint configuration.", label = "producer", required = "false")
private String componentName;
@@ -98,7 +98,7 @@ public final class RestSwaggerComponent extends DefaultComponent implements SSLC
description = "What payload type this component capable of consuming. Could be one type, like `application/json`"
+ " or multiple types as `application/json, application/xml; q=0.5` according to the RFC7231. This equates"
+ " to the value of `Accept` HTTP header. If set overrides any value found in the Swagger specification."
- + " Can be overriden in endpoint configuration",
+ + " Can be overridden in endpoint configuration",
label = "producer", required = "false")
private String consumes;
@@ -106,14 +106,14 @@ public final class RestSwaggerComponent extends DefaultComponent implements SSLC
+ " `http[s]://hostname[:port]`. Can be configured at the endpoint, component or in the correspoding"
+ " REST configuration in the Camel Context. If you give this component a name (e.g. `petstore`) that"
+ " REST configuration is consulted first, `rest-swagger` next, and global configuration last. If set"
- + " overrides any value found in the Swagger specification, RestConfiguration. Can be overriden in endpoint"
+ + " overrides any value found in the Swagger specification, RestConfiguration. Can be overridden in endpoint"
+ " configuration.", label = "producer", required = "false")
private String host;
@Metadata(
description = "What payload type this component is producing. For example `application/json`"
+ " according to the RFC7231. This equates to the value of `Content-Type` HTTP header. If set overrides"
- + " any value present in the Swagger specification. Can be overriden in endpoint configuration.",
+ + " any value present in the Swagger specification. Can be overridden in endpoint configuration.",
label = "producer", required = "false")
private String produces;
@@ -121,7 +121,7 @@ public final class RestSwaggerComponent extends DefaultComponent implements SSLC
+ " specification, but these can be overriden with properties on the component or endpoint level. If not"
+ " given the component tries to load `swagger.json` resource. Note that the `host` defined on the"
+ " component and endpoint of this Component should contain the scheme, hostname and optionally the"
- + " port in the URI syntax (i.e. `https://api.example.com:8080`). Can be overriden in endpoint"
+ + " port in the URI syntax (i.e. `https://api.example.com:8080`). Can be overridden in endpoint"
+ " configuration.", defaultValue = DEFAULT_SPECIFICATION_URI_STR, label = "producer", required = "false")
private URI specificationUri;
diff --git a/components/camel-rest-swagger/src/main/java/org/apache/camel/component/rest/swagger/RestSwaggerEndpoint.java b/components/camel-rest-swagger/src/main/java/org/apache/camel/component/rest/swagger/RestSwaggerEndpoint.java
index 93ff96e..2ee3f34 100644
--- a/components/camel-rest-swagger/src/main/java/org/apache/camel/component/rest/swagger/RestSwaggerEndpoint.java
+++ b/components/camel-rest-swagger/src/main/java/org/apache/camel/component/rest/swagger/RestSwaggerEndpoint.java
@@ -128,10 +128,14 @@ public final class RestSwaggerEndpoint extends DefaultEndpoint {
@UriPath(
description = "Path to the Swagger specification file. The scheme, host base path are taken from this"
- + " specification, but these can be overriden with properties on the component or endpoint level. If not"
- + " given the component tries to load `swagger.json` resource. Note that the `host` defined on the"
+ + " specification, but these can be overridden with properties on the component or endpoint level. If not"
+ + " given the component tries to load `swagger.json` resource from the classpath. Note that the `host` defined on the"
+ " component and endpoint of this Component should contain the scheme, hostname and optionally the"
- + " port in the URI syntax (i.e. `https://api.example.com:8080`). Overrides component configuration.",
+ + " port in the URI syntax (i.e. `http://api.example.com:8080`). Overrides component configuration."
+ + " The Swagger specification can be loaded from different sources by prefixing with file: classpath: http: https:."
+ + " Support for https is limited to using the JDK installed UrlHandler, and as such it can be cumbersome to setup"
+ + " TLS/SSL certificates for https (such as setting a number of javax.net.ssl JVM system properties)."
+ + " How to do that consult the JDK documentation for UrlHandler.",
defaultValue = RestSwaggerComponent.DEFAULT_SPECIFICATION_URI_STR,
defaultValueNote = "By default loads `swagger.json` file", label = "producer")
private URI specificationUri = RestSwaggerComponent.DEFAULT_SPECIFICATION_URI;
@@ -432,7 +436,7 @@ public final class RestSwaggerEndpoint extends DefaultEndpoint {
final boolean areTheSame = "rest-swagger".equals(assignedComponentName);
- throw new IllegalStateException("Unable to determine destionation host for requests. The Swagger specification"
+ throw new IllegalStateException("Unable to determine destination host for requests. The Swagger specification"
+ " does not specify `scheme` and `host` parameters, the specification URI is not absolute with `http` or"
+ " `https` scheme, and no RestConfigurations configured with `scheme`, `host` and `port` were found for `"
+ (areTheSame ? "rest-swagger` component" : assignedComponentName + "` or `rest-swagger` components")
@@ -569,7 +573,7 @@ public final class RestSwaggerEndpoint extends DefaultEndpoint {
final JsonNode node = mapper.readTree(stream);
return swaggerParser.read(node);
- } catch (final IOException e) {
+ } catch (Exception e) {
// try Swaggers loader
final Swagger swagger = swaggerParser.read(uriAsString);
@@ -580,7 +584,7 @@ public final class RestSwaggerEndpoint extends DefaultEndpoint {
throw new IllegalArgumentException("The given Swagger specification could not be loaded from `" + uri
+ "`. Tried loading using Camel's resource resolution and using Swagger's own resource resolution."
+ " Swagger tends to swallow exceptions while parsing, try specifying Java system property `debugParser`"
- + " (e.g. `-DdebugParser=true`), the exception that occured when loading using Camel's resource"
+ + " (e.g. `-DdebugParser=true`), the exception that occurred when loading using Camel's resource"
+ " loader follows", e);
}
}
diff --git a/components/camel-rest-swagger/src/main/java/org/apache/camel/component/rest/swagger/RestSwaggerHelper.java b/components/camel-rest-swagger/src/main/java/org/apache/camel/component/rest/swagger/RestSwaggerHelper.java
index ca7e972..28285e8 100644
--- a/components/camel-rest-swagger/src/main/java/org/apache/camel/component/rest/swagger/RestSwaggerHelper.java
+++ b/components/camel-rest-swagger/src/main/java/org/apache/camel/component/rest/swagger/RestSwaggerHelper.java
@@ -42,7 +42,7 @@ final class RestSwaggerHelper {
if (!matcher.matches()) {
throw new IllegalArgumentException(
- "host must be an apsolute URI (e.g. http://api.example.com), given: `" + hostUri + "`");
+ "host must be an absolute URI (e.g. http://api.example.com), given: `" + hostUri + "`");
}
return hostUri;
diff --git a/platforms/spring-boot/components-starter/camel-rest-swagger-starter/src/main/java/org/apache/camel/component/rest/swagger/springboot/RestSwaggerComponentConfiguration.java b/platforms/spring-boot/components-starter/camel-rest-swagger-starter/src/main/java/org/apache/camel/component/rest/swagger/springboot/RestSwaggerComponentConfiguration.java
index 08fe84d..5f14ed4 100644
--- a/platforms/spring-boot/components-starter/camel-rest-swagger-starter/src/main/java/org/apache/camel/component/rest/swagger/springboot/RestSwaggerComponentConfiguration.java
+++ b/platforms/spring-boot/components-starter/camel-rest-swagger-starter/src/main/java/org/apache/camel/component/rest/swagger/springboot/RestSwaggerComponentConfiguration.java
@@ -43,11 +43,11 @@ public class RestSwaggerComponentConfiguration
*/
private String basePath;
/**
- * Name of the Camel component that will perform the requests. The compnent
+ * Name of the Camel component that will perform the requests. The component
* must be present in Camel registry and it must implement
* RestProducerFactory service provider interface. If not set CLASSPATH is
* searched for single component that implements RestProducerFactory SPI.
- * Can be overriden in endpoint configuration.
+ * Can be overridden in endpoint configuration.
*/
private String componentName;
/**
@@ -55,7 +55,7 @@ public class RestSwaggerComponentConfiguration
* like application/json or multiple types as application/json,
* application/xml; q=0.5 according to the RFC7231. This equates to the
* value of Accept HTTP header. If set overrides any value found in the
- * Swagger specification. Can be overriden in endpoint configuration
+ * Swagger specification. Can be overridden in endpoint configuration
*/
private String consumes;
/**
@@ -65,14 +65,14 @@ public class RestSwaggerComponentConfiguration
* this component a name (e.g. petstore) that REST configuration is
* consulted first, rest-swagger next, and global configuration last. If set
* overrides any value found in the Swagger specification,
- * RestConfiguration. Can be overriden in endpoint configuration.
+ * RestConfiguration. Can be overridden in endpoint configuration.
*/
private String host;
/**
* What payload type this component is producing. For example
* application/json according to the RFC7231. This equates to the value of
* Content-Type HTTP header. If set overrides any value present in the
- * Swagger specification. Can be overriden in endpoint configuration.
+ * Swagger specification. Can be overridden in endpoint configuration.
*/
private String produces;
/**
@@ -82,7 +82,7 @@ public class RestSwaggerComponentConfiguration
* load swagger.json resource. Note that the host defined on the component
* and endpoint of this Component should contain the scheme, hostname and
* optionally the port in the URI syntax (i.e.
- * https://api.example.com:8080). Can be overriden in endpoint
+ * https://api.example.com:8080). Can be overridden in endpoint
* configuration.
*/
private URI specificationUri;