Add automatic URI detection for OpenAPI document configuration

- Enhanced CallOpenAPITaskFluent.document(String) to automatically detect whether the input is a literal URI or a JQ runtime expression
- Added EndpointUtil.isJqExpr() helper method to identify JQ expressions (strings starting with "${" )
- Added comprehensive test coverage with FuncOpenAPITest using MockWebServer
- Added serverlessworkflow-impl-openapi dependency to experimental/test module
- Updated .gitignore to exclude Bob-Shell notes directory

The document() method now intelligently handles both:
  - Literal URI strings (e.g., "http://example.com/swagger.json")
  - JQ runtime expressions (e.g., "${.openapi.url}")

This improves the developer experience by eliminating the need to choose between document(String) and document(URI) methods based on the input type.

Closes #1303

Signed-off-by: Matheus Cruz <matheuscruz.dev@gmail.com>

Author: mcruzdev

.gitignore

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

experimental/test/pom.xml

@@ -72,6 +72,11 @@
             <groupId>io.serverlessworkflow</groupId>
             <artifactId>serverlessworkflow-impl-jq</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.serverlessworkflow</groupId>
+            <artifactId>serverlessworkflow-impl-openapi</artifactId>
+            <version>${project.version}</version>
+        </dependency>
         <dependency>
             <groupId>org.glassfish.jersey.media</groupId>
             <artifactId>jersey-media-json-jackson</artifactId>

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/CallOpenAPITaskFluent.java

@@ -40,11 +40,24 @@ 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)));
+    if (EndpointUtil.isJqExpr(uri)) {
+      ((CallOpenAPI) this.self().getTask())
+          .getWith()
+          .withDocument(
+              new ExternalResource().withEndpoint(new Endpoint().withRuntimeExpression(uri)));
+    } else {
+      return document(URI.create(uri));
+    }
     return self();
   }
 

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

@@ -63,4 +63,8 @@ private static boolean isUrlLike(String value) {
     }
     return true;
   }
+
+  public static boolean isJqExpr(String expr) {
+    return expr != null && expr.startsWith("${");
+  }
 }