CAMEL-25887: camel-rest-openapi - option to restrict the external references of the OpenAPI specification

catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/components/rest-openapi.json

@@ -43,8 +43,9 @@
     "consumes": { "index": 16, "kind": "property", "displayName": "Consumes", "group": "producer (advanced)", "label": "producer,advanced", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "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 OpenApi specification. Can be overridden in endpoint configuration" },
     "produces": { "index": 17, "kind": "property", "displayName": "Produces", "group": "producer (advanced)", "label": "producer,advanced", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "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 OpenApi specification. Can be overridden in endpoint configuration." },
     "autowiredEnabled": { "index": 18, "kind": "property", "displayName": "Autowired Enabled", "group": "advanced", "label": "advanced", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "autowired": false, "secret": false, "defaultValue": true, "description": "Whether autowiring is enabled. This is used for automatic autowiring options (the option must be marked as autowired) by looking up in the registry to find if there is a single instance of matching type, which then gets configured on the component. This can be used for automatic configuring JDBC data sources, JMS connection factories, AWS Clients, etc." },
-    "sslContextParameters": { "index": 19, "kind": "property", "displayName": "Ssl Context Parameters", "group": "security", "label": "security", "required": false, "type": "object", "javaType": "org.apache.camel.support.jsse.SSLContextParameters", "deprecated": false, "autowired": false, "secret": false, "description": "Customize TLS parameters used by the component. If not set defaults to the TLS parameters set in the Camel context" },
-    "useGlobalSslContextParameters": { "index": 20, "kind": "property", "displayName": "Use Global Ssl Context Parameters", "group": "security", "label": "security", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "autowired": false, "secret": false, "defaultValue": false, "description": "Enable usage of global SSL context parameters." }
+    "externalReferences": { "index": 19, "kind": "property", "displayName": "External References", "group": "security", "label": "security", "required": false, "type": "enum", "javaType": "java.lang.String", "enum": [ "all", "local", "none" ], "deprecated": false, "autowired": false, "secret": false, "defaultValue": "all", "description": "Which external references ($ref) the OpenAPI specification may use: all allows any reference, local allows references to the classpath and the file system only, and none allows only references inside the document. A reference the option does not allow fails the start. Can be overridden in endpoint configuration." },
+    "sslContextParameters": { "index": 20, "kind": "property", "displayName": "Ssl Context Parameters", "group": "security", "label": "security", "required": false, "type": "object", "javaType": "org.apache.camel.support.jsse.SSLContextParameters", "deprecated": false, "autowired": false, "secret": false, "description": "Customize TLS parameters used by the component. If not set defaults to the TLS parameters set in the Camel context" },
+    "useGlobalSslContextParameters": { "index": 21, "kind": "property", "displayName": "Use Global Ssl Context Parameters", "group": "security", "label": "security", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "autowired": false, "secret": false, "defaultValue": false, "description": "Enable usage of global SSL context parameters." }
   },
   "properties": {
     "specificationUri": { "index": 0, "kind": "path", "displayName": "Specification Uri", "group": "common", "label": "common", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "defaultValue": "openapi.json", "description": "Path to the OpenApi 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 openapi.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 component configuration. The OpenApi 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. Default value notice: By default loads openapi.json file" },
@@ -67,6 +68,7 @@
     "requestValidationEnabled": { "index": 17, "kind": "parameter", "displayName": "Request Validation Enabled", "group": "producer", "label": "producer", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "autowired": false, "secret": false, "defaultValue": false, "description": "Enable validation of requests against the configured OpenAPI specification" },
     "componentName": { "index": 18, "kind": "parameter", "displayName": "Component Name", "group": "producer (advanced)", "label": "producer,advanced", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "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. Overrides component configuration." },
     "lazyStartProducer": { "index": 19, "kind": "parameter", "displayName": "Lazy Start Producer", "group": "producer (advanced)", "label": "producer,advanced", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "autowired": false, "secret": false, "defaultValue": false, "description": "Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing." },
-    "oauthProfile": { "index": 20, "kind": "parameter", "displayName": "OAuth Profile", "group": "security", "label": "consumer,security", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "description": "OAuth profile name passed to the HTTP consumer delegate for validating incoming Authorization: Bearer tokens. The selected consumer component must support the oauthProfile option; delegates that ignore unknown options will start without endpoint protection." }
+    "externalReferences": { "index": 20, "kind": "parameter", "displayName": "External References", "group": "security", "label": "security", "required": false, "type": "enum", "javaType": "java.lang.String", "enum": [ "all", "local", "none" ], "deprecated": false, "autowired": false, "secret": false, "defaultValue": "all", "description": "Which external references ($ref) the OpenAPI specification may use. The parser loads every external reference when the consumer or producer is created, from the classpath, the file system or over http(s). all allows any reference, local allows references to the classpath and the file system only, and none allows only references inside the document. A reference the option does not allow fails the start, before the parser loads anything. Overrides component configuration." },
+    "oauthProfile": { "index": 21, "kind": "parameter", "displayName": "OAuth Profile", "group": "security", "label": "consumer,security", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "description": "OAuth profile name passed to the HTTP consumer delegate for validating incoming Authorization: Bearer tokens. The selected consumer component must support the oauthProfile option; delegates that ignore unknown options will start without endpoint protection." }
   }
 }

catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/rest-openapi-component.adoc

@@ -330,6 +330,35 @@ so a misconfigured delegate cannot start without the expected protection. Custom
 enforce the option must override `RestOpenApiConsumerFactory.supportsOAuthProfile()` to return
 `true`.
 
+=== Restricting the external references of the specification
+
+An OpenAPI specification can reference other documents with `$ref`: files on the classpath or the file system,
+and documents on an http(s) server. The parser loads every such document when the consumer or producer is
+created, and a document it loads can reference further documents. The `externalReferences` option, on the
+endpoint or the component, restricts this:
+
+* `all` (default) allows any reference.
+* `local` allows references to the classpath and the file system only. A specification loaded from a URL may
+  then reference no other document at all, because the parser resolves its references against that URL.
+* `none` allows only references inside the document, such as `#/components/schemas/Pet`.
+
+The check runs before the parser resolves anything, on the document tree the parser uses (YAML aliases expanded).
+It resolves every `$ref` the way the parser does: against the document that contains it and, for OpenAPI 3.1,
+against the enclosing `$id`. `file:` and `classpath:` references count as local. The local documents the option
+allows are read and checked in turn, and a document that cannot be read fails the check. A reference the option
+does not allow fails the start, with a message that names the reference and where it is.
+
+[source,java]
+----
+from("direct:getPetById")
+    .to("rest-openapi:petstore-v3.json#getPetById?externalReferences=local");
+----
+
+The option can also be set once on the component, for example with
+`camel.component.rest-openapi.external-references=none`. For the contract-first Rest DSL, set it on the `openApi`
+element as shown in xref:manual::rest-dsl-openapi.adoc[REST DSL with contract-first OpenAPI]; the component setting
+applies there as well, also to the specification served as api-doc.
+
 == Request validation
 
 API requests can be validated against the configured OpenAPI specification before they are sent by setting the `requestValidationEnabled` option to `true`.

catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/models/openApi.json

@@ -21,6 +21,7 @@
     "routeId": { "index": 6, "kind": "attribute", "displayName": "Route Id", "group": "common", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "description": "The route id." },
     "missingOperation": { "index": 7, "kind": "attribute", "displayName": "Missing Operation", "group": "common", "required": false, "type": "enum", "javaType": "java.lang.String", "enum": [ "fail", "ignore", "mock" ], "deprecated": false, "autowired": false, "secret": false, "defaultValue": "fail", "description": "Whether to fail, ignore or return a mock response for OpenAPI operations that are not mapped to a corresponding route." },
     "unmatchedRequestHandling": { "index": 8, "kind": "attribute", "displayName": "Unmatched Request Handling", "group": "common", "required": false, "type": "enum", "javaType": "java.lang.String", "enum": [ "platform", "camel" ], "deprecated": false, "autowired": false, "secret": false, "defaultValue": "platform", "description": "Who answers requests that match no operation in the OpenAPI specification: the HTTP layer (platform) or Camel via the unmatched request handler (camel)." },
-    "mockIncludePattern": { "index": 9, "kind": "attribute", "displayName": "Mock Include Pattern", "group": "advanced", "label": "advanced", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "defaultValue": "classpath:camel-mock\/**", "description": "Used for inclusive filtering of mock data from directories. The pattern is using Ant-path style pattern. Multiple patterns can be specified separated by comma." }
+    "mockIncludePattern": { "index": 9, "kind": "attribute", "displayName": "Mock Include Pattern", "group": "advanced", "label": "advanced", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "defaultValue": "classpath:camel-mock\/**", "description": "Used for inclusive filtering of mock data from directories. The pattern is using Ant-path style pattern. Multiple patterns can be specified separated by comma." },
+    "externalReferences": { "index": 10, "kind": "attribute", "displayName": "External References", "group": "security", "label": "security", "required": false, "type": "enum", "javaType": "java.lang.String", "enum": [ "all", "local", "none" ], "deprecated": false, "autowired": false, "secret": false, "defaultValue": "all", "description": "Which external references ($ref) the OpenAPI specification may use: all allows any reference, local allows references to the classpath and the file system only, and none allows only references inside the document. A reference the option does not allow fails the start." }
   }
 }

catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/schemas/camel-spring.xsd

@@ -15655,6 +15655,17 @@ unmatched request handler (camel). Default value: platform
 <![CDATA[
 Used for inclusive filtering of mock data from directories. The pattern is using Ant-path style pattern. Multiple
 patterns can be specified separated by comma. Default value: classpath:camel-mock/**
+]]>
+            </xs:documentation>
+          </xs:annotation>
+        </xs:attribute>
+        <xs:attribute name="externalReferences" type="xs:string">
+          <xs:annotation>
+            <xs:documentation xml:lang="en">
+<![CDATA[
+Which external references ($ref) the OpenAPI specification may use: all allows any reference, local allows references to
+the classpath and the file system only, and none allows only references inside the document. A reference the option does
+not allow fails the start. Default value: all
 ]]>
             </xs:documentation>
           </xs:annotation>

catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/schemas/camel-xml-io.xsd

@@ -14798,6 +14798,17 @@ unmatched request handler (camel). Default value: platform
 <![CDATA[
 Used for inclusive filtering of mock data from directories. The pattern is using Ant-path style pattern. Multiple
 patterns can be specified separated by comma. Default value: classpath:camel-mock/**
+]]>
+            </xs:documentation>
+          </xs:annotation>
+        </xs:attribute>
+        <xs:attribute name="externalReferences" type="xs:string">
+          <xs:annotation>
+            <xs:documentation xml:lang="en">
+<![CDATA[
+Which external references ($ref) the OpenAPI specification may use: all allows any reference, local allows references to
+the classpath and the file system only, and none allows only references inside the document. A reference the option does
+not allow fails the start. Default value: all
 ]]>
             </xs:documentation>
           </xs:annotation>

catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/schemas/camelYamlDsl-model.json

@@ -17755,6 +17755,18 @@
         "index" : 9,
         "group" : "advanced",
         "label" : "advanced"
+      }, {
+        "name" : "externalReferences",
+        "type" : "enum",
+        "enum" : [ "all", "local", "none" ],
+        "description" : "Which external references ($ref) the OpenAPI specification may use: all allows any reference, local allows references to the classpath and the file system only, and none allows only references inside the document. A reference the option does not allow fails the start.",
+        "title" : "External References",
+        "default" : "all",
+        "displayName" : "External References",
+        "kind" : "attribute",
+        "index" : 10,
+        "group" : "security",
+        "label" : "security"
       } ]
     },
     "openIdConnect" : {