Add automatic URI detection for OpenAPI document configuration by mcruzdev · Pull Request #1319 · serverlessworkflow/sdk-java

mcruzdev · 2026-04-15T15:00:18Z

Changes

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

Copilot

Pull request overview

Improves the fluent OpenAPI task builder to accept a document(String) that can represent either a literal OpenAPI document URI or a runtime (JQ) expression, aiming to prevent JsonQueryException when users pass URL strings (Issue #1303).

Changes:

Added EndpointUtil.isJqExpr() to identify JQ-style ${...} expressions.
Updated CallOpenAPITaskFluent.document(String) to route ${...} to runtimeExpression and everything else to document(URI).
Added an experimental integration test using MockWebServer, plus a new OpenAPI impl dependency for the experimental test module.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/spi/EndpointUtil.java	Adds a helper for detecting `${...}` expressions.
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/spi/CallOpenAPITaskFluent.java	Changes `document(String)` to auto-detect literal vs expression.
experimental/test/src/test/java/io/serverlessworkflow/fluent/test/FuncOpenAPITest.java	Adds a MockWebServer-based OpenAPI execution test.
experimental/test/pom.xml	Adds the OpenAPI implementation dependency for tests.
.gitignore	Ignores `.bob/notes/` and normalizes `.vscode/` entry.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-15T15:06:47Z

+        FuncWorkflowBuilder.workflow("openapi-call-workflow")
+            .tasks(
+                openapi()
+                    .document(URI.create(mockWebServer.url("/v2/swagger.json").toString()))
+                    .operation("findPetsByStatus")
+                    .parameters(Map.of("status", "available")))


This test is named as if it validates the new auto-detection in document(String), but it calls document(URI) (line 94) and therefore never exercises the updated logic that distinguishes literal URIs from JQ expressions. To prevent regressions of #1303, update/add assertions to cover openapi().document(mockWebServer.url(...).toString()) (string overload) and (ideally) a ${...} / raw-JQ case to ensure it still gets treated as a runtime expression.

fjtirado · 2026-04-16T10:15:48Z

This one should be deleted

fjtirado · 2026-04-16T15:54:34Z

@mcruzdev see mcruzdev#5

Copilot

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-16T16:45:00Z

+  @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();


This test is named as if it validates the new document(String) auto-detection behavior, but it currently calls the document(URI) overload. That means it won’t catch regressions of the original issue (passing a URL as a string being treated as a JQ expression). Consider switching to document(mockWebServer.url("/v2/swagger.json").toString()) and/or adding an explicit test that document(String) with an http(s)://... value loads successfully (and optionally a separate test for a real JQ expression string).

Copilot

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-16T18:50:40Z

+  public static Endpoint fromString(String uri) {
+    return fromString(uri, null);
+  }
+
+  public static Endpoint fromString(String uri, ReferenceableAuthenticationPolicy auth) {
+    Objects.requireNonNull(uri, "Endpoint URI cannot be null");
+    String trimmed = uri.trim();
    Endpoint endpoint = new Endpoint();
-    if (isUrlLike(trimmed)) {
-      UriTemplate template = new UriTemplate();
-      if (trimmed.indexOf('{') >= 0 || trimmed.indexOf('}') >= 0) {
-        template.setLiteralUriTemplate(trimmed);
-      } else {
-        template.setLiteralUri(URI.create(trimmed));
-      }
-      endpoint.setUriTemplate(template);
-      return endpoint;
-    }



The PR description says a new EndpointUtil.isJqExpr() helper was added to detect JQ expressions (strings starting with "${"), but there is no such method in this change set (and no references found in the repo). Either add the helper (and use it where intended) or update the PR description to match the implemented URL-vs-expression detection logic.

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

Copilot

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-16T21:28:53Z

+  /**
+   * 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
+   */


The Javadoc says this method detects "literal URI vs JQ runtime expression", but the implementation delegates to EndpointUtil.fromString(...) which classifies inputs as literal only when they look like scheme://... (and treats everything else as an expression). Consider tightening the wording to match the actual behavior (e.g., require a URI scheme) or adjusting the detection logic so it aligns with the documented JQ vs literal distinction.

mcruzdev requested a review from fjtirado as a code owner April 15, 2026 15:00

Copilot AI review requested due to automatic review settings April 15, 2026 15:00

Copilot started reviewing on behalf of mcruzdev April 15, 2026 15:00 View session

mcruzdev force-pushed the issue-1303 branch from 6e628a9 to cd046db Compare April 15, 2026 15:00

Copilot AI reviewed Apr 15, 2026

View reviewed changes

fjtirado reviewed Apr 16, 2026

View reviewed changes

Comment thread .gitignore

Copy link
Copy Markdown

Collaborator

fjtirado Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one should be deleted

fjtirado marked this pull request as draft April 16, 2026 10:23

fjtirado marked this pull request as ready for review April 16, 2026 16:34

Copilot AI review requested due to automatic review settings April 16, 2026 16:34

Copilot started reviewing on behalf of fjtirado April 16, 2026 16:38 View session

Copilot AI reviewed Apr 16, 2026

View reviewed changes

fjtirado self-requested a review April 16, 2026 18:13

fjtirado approved these changes Apr 16, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings April 16, 2026 18:45

Copilot AI reviewed Apr 16, 2026

View reviewed changes

Refactor how endpoint and authentication are handled in the fluent API

124653c

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

Copilot AI review requested due to automatic review settings April 16, 2026 21:22

mcruzdev force-pushed the issue-1303 branch from e18f20e to 124653c Compare April 16, 2026 21:22

Copilot started reviewing on behalf of mcruzdev April 16, 2026 21:23 View session

fjtirado merged commit 4062fc4 into serverlessworkflow:main Apr 16, 2026
5 checks passed

Copilot AI reviewed Apr 16, 2026

View reviewed changes

Conversation

mcruzdev commented Apr 15, 2026

Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

fjtirado Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

fjtirado commented Apr 16, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants