Add automatic URI detection for OpenAPI document configuration

.gitignore

@@ -29,4 +29,7 @@ target/
 build/
 
 ### VS Code ###
-.vscode/
+.vscode/
+
+# Bob-Shell
+.bob/notes/

experimental/fluent/func/src/test/java/io/serverlessworkflow/fluent/func/FuncDSLTest.java

@@ -266,7 +266,13 @@ void get_named_with_authentication_uses_auth_policy() {
     assertEquals("GET", http.getWith().getMethod());
     assertEquals(
         "http://service/api/users",
-        http.getWith().getEndpoint().getUriTemplate().getLiteralUri().toString(),
+        http.getWith()
+            .getEndpoint()
+            .getEndpointConfiguration()
+            .getUri()
+            .getLiteralEndpointURI()
+            .getLiteralUri()
+            .toString(),
         "endpoint should be set from get(name, endpoint, auth)");
 
     assertNotNull(
@@ -304,7 +310,13 @@ void get_with_uri_and_authentication() {
     assertEquals("GET", http.getWith().getMethod());
     assertEquals(
         endpoint.toString(),
-        http.getWith().getEndpoint().getUriTemplate().getLiteralUri().toString(),
+        http.getWith()
+            .getEndpoint()
+            .getEndpointConfiguration()
+            .getUri()
+            .getLiteralEndpointURI()
+            .getLiteralUri()
+            .toString(),
         "endpoint should be derived from URI");
 
     assertNotNull(http.getWith().getEndpoint().getEndpointConfiguration().getAuthentication());
@@ -371,7 +383,13 @@ void post_named_with_authentication() {
     assertEquals("POST", http.getWith().getMethod());
     assertEquals(
         "https://orders.example.com/api/orders",
-        http.getWith().getEndpoint().getUriTemplate().getLiteralUri().toString());
+        http.getWith()
+            .getEndpoint()
+            .getEndpointConfiguration()
+            .getUri()
+            .getLiteralEndpointURI()
+            .getLiteralUri()
+            .toString());
     assertEquals(body, http.getWith().getBody());
 
     assertNotNull(http.getWith().getEndpoint().getEndpointConfiguration().getAuthentication());
@@ -409,7 +427,13 @@ void call_with_preconfigured_http_spec() {
     assertEquals("POST", http.getWith().getMethod());
     assertEquals(
         "http://service/api",
-        http.getWith().getEndpoint().getUriTemplate().getLiteralUri().toString());
+        http.getWith()
+            .getEndpoint()
+            .getEndpointConfiguration()
+            .getUri()
+            .getLiteralEndpointURI()
+            .getLiteralUri()
+            .toString());
     assertEquals(
         "svc-auth",
         http.getWith()

experimental/test/pom.xml

@@ -71,6 +71,13 @@
         <dependency>
             <groupId>io.serverlessworkflow</groupId>
             <artifactId>serverlessworkflow-impl-jq</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.serverlessworkflow</groupId>
+            <artifactId>serverlessworkflow-impl-openapi</artifactId>
+            <version>${project.version}</version>
+            <scope>test</scope>
         </dependency>
         <dependency>
             <groupId>org.glassfish.jersey.media</groupId>

experimental/test/src/test/java/io/serverlessworkflow/fluent/test/FuncOpenAPITest.java

@@ -0,0 +1,112 @@
+/*
+ * Copyright 2020-Present The Serverless Workflow Specification Authors
+ *
+ * Licensed 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 io.serverlessworkflow.fluent.test;
+
+import static io.serverlessworkflow.fluent.func.dsl.FuncDSL.openapi;
+
+import io.serverlessworkflow.fluent.func.FuncWorkflowBuilder;
+import io.serverlessworkflow.impl.WorkflowApplication;
+import io.serverlessworkflow.impl.WorkflowDefinition;
+import io.serverlessworkflow.impl.WorkflowInstance;
+import io.serverlessworkflow.impl.WorkflowModel;
+import java.io.IOException;
+import java.net.URI;
+import java.util.Map;
+import mockwebserver3.MockResponse;
+import mockwebserver3.MockWebServer;
+import okhttp3.Headers;
+import org.assertj.core.api.SoftAssertions;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+public class FuncOpenAPITest {
+
+  private static MockWebServer mockWebServer;
+
+  @BeforeEach
+  public void setup() throws IOException {
+    mockWebServer = new MockWebServer();
+    mockWebServer.start(0);
+  }
+
+  @AfterEach
+  public void tearDown() {
+    mockWebServer.close();
+  }
+
+  @Test
+  void test_openapi_document_with_non_jq_uri_string() {
+    String mockedSwaggerDoc =
+        """
+                {
+                  "swagger": "2.0",
+                  "info": { "version": "1.0.0", "title": "Mock Petstore" },
+                  "host": "localhost:%d",
+                  "basePath": "/v2",
+                  "schemes": [ "http" ],
+                  "paths": {
+                    "/pet/findByStatus": {
+                      "get": {
+                        "operationId": "findPetsByStatus",
+                        "parameters": [
+                          {
+                            "name": "status",
+                            "in": "query",
+                            "required": true,
+                            "type": "string"
+                          }
+                        ],
+                        "responses": { "200": { "description": "OK" } }
+                      }
+                    }
+                  }
+                }
+                """
+            .formatted(mockWebServer.getPort());
+
+    mockWebServer.enqueue(
+        new MockResponse(200, Headers.of("Content-Type", "application/json"), mockedSwaggerDoc));
+    mockWebServer.enqueue(
+        new MockResponse(
+            200,
+            Headers.of("Content-Type", "application/json"),
+            """
+                { "description": "OK" }
+                """));
+    var w =
+        FuncWorkflowBuilder.workflow("openapi-call-workflow")
+            .tasks(
+                openapi()
+                    .document(URI.create(mockWebServer.url("/v2/swagger.json").toString()))
+                    .operation("findPetsByStatus")
+                    .parameters(Map.of("status", "available")))
+            .build();
+
+    try (WorkflowApplication app = WorkflowApplication.builder().build()) {
+
+      WorkflowDefinition def = app.workflowDefinition(w);
+      WorkflowInstance instance = def.instance(Map.of());
+      WorkflowModel model = instance.start().join();
+
+      SoftAssertions.assertSoftly(
+          softly -> {
+            softly.assertThat(model).isNotNull();
+            softly.assertThat(model.asMap()).contains(Map.of("description", "OK"));
+          });
+    }
+  }
+}

fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/spi/CallHttpTaskFluent.java

@@ -50,57 +50,89 @@ default SELF method(String method) {
     return self();
   }
 
+  /**
+   * Sets the endpoint URI for the HTTP call.
+   *
+   * @param endpoint the URI to call
+   * @return this builder instance for method chaining
+   */
   default SELF endpoint(URI endpoint) {
     ((CallHTTP) this.self().getTask())
         .getWith()
         .setEndpoint(new Endpoint().withUriTemplate(new UriTemplate().withLiteralUri(endpoint)));
     return self();
   }
 
+  /**
+   * Sets the endpoint URI for the HTTP call with authentication configuration.
+   *
+   * @param endpoint the URI to call
+   * @param auth consumer to configure authentication policy
+   * @return this builder instance for method chaining
+   */
   default SELF endpoint(URI endpoint, Consumer<ReferenceableAuthenticationPolicyBuilder> auth) {
     final ReferenceableAuthenticationPolicyBuilder policy =
         new ReferenceableAuthenticationPolicyBuilder();
-    final UriTemplate uriTemplate = new UriTemplate().withLiteralUri(endpoint);
     auth.accept(policy);
     ((CallHTTP) this.self().getTask())
         .getWith()
         .setEndpoint(
             new Endpoint()
                 .withEndpointConfiguration(
                     new EndpointConfiguration()
-                        .withUri(new EndpointUri().withLiteralEndpointURI(uriTemplate))
-                        .withAuthentication(policy.build()))
-                .withUriTemplate(uriTemplate));
+                        .withUri(
+                            new EndpointUri()
+                                .withLiteralEndpointURI(new UriTemplate().withLiteralUri(endpoint)))
+                        .withAuthentication(policy.build())));
     return self();
   }
 
+  /**
+   * Sets the endpoint using a runtime expression or URI string.
+   *
+   * @param expr the runtime expression or URI string for the endpoint
+   * @return this builder instance for method chaining
+   */
   default SELF endpoint(String expr) {
     ((CallHTTP) this.self().getTask()).getWith().setEndpoint(EndpointUtil.fromString(expr));
     return self();
   }
 
+  /**
+   * Sets the endpoint using a runtime expression or URI string with authentication configuration.
+   *
+   * @param expr the runtime expression or URI string for the endpoint
+   * @param auth consumer to configure authentication policy
+   * @return this builder instance for method chaining
+   */
   default SELF endpoint(String expr, Consumer<ReferenceableAuthenticationPolicyBuilder> auth) {
     final ReferenceableAuthenticationPolicyBuilder policy =
         new ReferenceableAuthenticationPolicyBuilder();
     auth.accept(policy);
 
-    final Endpoint endpoint = EndpointUtil.fromString(expr);
-    endpoint.setEndpointConfiguration(
-        new EndpointConfiguration().withAuthentication(policy.build()));
-
-    ((CallHTTP) this.self().getTask()).getWith().setEndpoint(endpoint);
+    ((CallHTTP) this.self().getTask())
+        .getWith()
+        .setEndpoint(EndpointUtil.fromString(expr, policy.build()));
     return self();
   }
 
+  /**
+   * Sets the endpoint using a runtime expression or URI string with authentication policy
+   * reference.
+   *
+   * @param expr the runtime expression or URI string for the endpoint
+   * @param authUse the name of the authentication policy to reference
+   * @return this builder instance for method chaining
+   */
   default SELF endpoint(String expr, String authUse) {
-    final Endpoint endpoint = EndpointUtil.fromString(expr);
-    endpoint.withEndpointConfiguration(
-        new EndpointConfiguration()
-            .withAuthentication(
+    ((CallHTTP) this.self().getTask())
+        .getWith()
+        .setEndpoint(
+            EndpointUtil.fromString(
+                expr,
                 new ReferenceableAuthenticationPolicy()
                     .withAuthenticationPolicyReference(
                         new AuthenticationPolicyReference(authUse))));
-    ((CallHTTP) this.self().getTask()).getWith().setEndpoint(endpoint);
     return self();
   }
 

fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/spi/CallOpenAPITaskFluent.java

@@ -21,6 +21,7 @@
 import io.serverlessworkflow.api.types.EndpointUri;
 import io.serverlessworkflow.api.types.ExternalResource;
 import io.serverlessworkflow.api.types.OpenAPIArguments;
+import io.serverlessworkflow.api.types.ReferenceableAuthenticationPolicy;
 import io.serverlessworkflow.api.types.UriTemplate;
 import io.serverlessworkflow.fluent.spec.ReferenceableAuthenticationPolicyBuilder;
 import io.serverlessworkflow.fluent.spec.TaskBaseBuilder;
@@ -40,11 +41,19 @@ default CallOpenAPI build() {
 
   SELF self();
 
+  /**
+   * Sets the OpenAPI document location. This method automatically detects whether the provided
+   * string is a literal URI or a JQ runtime expression.
+   *
+   * @param uri the OpenAPI document location as either a literal URI string or a JQ expression
+   * @return this builder instance for method chaining
+   * @see #document(URI) for setting a literal URI directly
+   * @see #document(String, AuthenticationConfigurer) for setting a document with authentication
+   */
   default SELF document(String uri) {
     ((CallOpenAPI) this.self().getTask())
         .getWith()
-        .withDocument(
-            new ExternalResource().withEndpoint(new Endpoint().withRuntimeExpression(uri)));
+        .setDocument(new ExternalResource().withEndpoint(EndpointUtil.fromString(uri)));
     return self();
   }
 
@@ -62,41 +71,33 @@ default SELF document(String uri, AuthenticationConfigurer authenticationConfigu
     final ReferenceableAuthenticationPolicyBuilder policy =
         new ReferenceableAuthenticationPolicyBuilder();
     authenticationConfigurer.accept(policy);
-    ((CallOpenAPI) this.self().getTask()).getWith().setAuthentication(policy.build());
+    ReferenceableAuthenticationPolicy auth = policy.build();
+    ((CallOpenAPI) this.self().getTask()).getWith().setAuthentication(auth);
     ((CallOpenAPI) this.self().getTask())
         .getWith()
-        .setDocument(
-            new ExternalResource()
-                .withEndpoint(
-                    new Endpoint()
-                        .withRuntimeExpression(uri)
-                        .withEndpointConfiguration(
-                            new EndpointConfiguration()
-                                .withUri(new EndpointUri().withExpressionEndpointURI(uri))
-                                .withAuthentication(policy.build()))));
+        .setDocument(new ExternalResource().withEndpoint(EndpointUtil.fromString(uri, auth)));
     return self();
   }
 
   default SELF document(URI uri, AuthenticationConfigurer authenticationConfigurer) {
     final ReferenceableAuthenticationPolicyBuilder policy =
         new ReferenceableAuthenticationPolicyBuilder();
     authenticationConfigurer.accept(policy);
-
-    ((CallOpenAPI) this.self().getTask()).getWith().setAuthentication(policy.build());
+    ReferenceableAuthenticationPolicy auth = policy.build();
+    ((CallOpenAPI) this.self().getTask()).getWith().setAuthentication(auth);
     ((CallOpenAPI) this.self().getTask())
         .getWith()
         .setDocument(
             new ExternalResource()
                 .withEndpoint(
                     new Endpoint()
-                        .withUriTemplate(new UriTemplate().withLiteralUri(uri))
                         .withEndpointConfiguration(
                             new EndpointConfiguration()
                                 .withUri(
                                     new EndpointUri()
                                         .withLiteralEndpointURI(
                                             new UriTemplate().withLiteralUri(uri)))
-                                .withAuthentication(policy.build()))));
+                                .withAuthentication(auth))));
     return self();
   }