Authoring & Leveraging Arazzo Spec for OpenAPI & AsyncAPI Workflow Testing

Arazzo API spec workflow test: Authoring and Running OpenAPI + AsyncAPI Workflows

In this walkthrough I explain how to author and run an Arazzo API spec workflow test that mixes synchronous OpenAPI operations with asynchronous AsyncAPI (Kafka) operations. As the creator of the demo, I’ll guide you step-by-step: authoring a visual workflow from API specs, exporting it as an Arazzo API specification, supplying test data, and running the end-to-end workflow test using Specmatic and a running application.

Why a combined OpenAPI + AsyncAPI workflow?

Modern distributed systems often combine synchronous REST endpoints and asynchronous messaging patterns. For example, a back-end-for-front-end (BFF) might:

• Call a location service (synchronous) to get a user’s location.
• Call a product service (synchronous) to fetch products available at that location.
• Send an order creation message to Kafka (asynchronous), and wait for confirmation on another Kafka topic.
• Finally call an order service (synchronous) to fetch order details.

Modeling and testing such journeys requires a workflow definition that understands both synchronous (OpenAPI) and asynchronous (AsyncAPI) operations. An Arazzo API spec workflow test lets you author that journey visually and then run it against your running services to validate behavior across the entire end-to-end path.

Overview of the demo workflow

In the demonstration I built a workflow called “place order” that looks like this logically:

1. Get user location (GET user details via OpenAPI)
2. Get products available at that location (GET products via OpenAPI)
3. Create order by sending an asynchronous message to a Kafka topic (AsyncAPI)
4. Receive order confirmation on a Kafka topic (AsyncAPI)
5. Get order details via a synchronous OpenAPI call

That sequence mixes synchronous and asynchronous steps and includes branching based on success/failure or data conditions. For example, if the products array returned is empty, subsequent steps (create order, Kafka exchange) are skipped and the workflow ends.

Step 1 — Author the workflow visually

I started by opening a workflow authoring canvas in Specmatic and added a few boxes to represent each operation. The visual editor supports dragging API operations directly from OpenAPI and AsyncAPI specifications into the canvas. I used two OpenAPI specs (location service and order service) and one AsyncAPI spec (Kafka-based order service).

For each operation I:

• Dragged the operation into the canvas (for example, Get User Details).
• Renamed nodes for clarity (Create Order, Order Confirmation, Get Order).
• Connected the nodes to indicate the intended sequence.

Once connected I used the auto-layout feature to tidy the diagram. Then I asked the editor to generate the detailed workflow. This generation step expands the visual outline into a workflow with decision points and success criteria (e.g., HTTP 2xx, non-empty arrays, expected Kafka responses).

Step 2 — Export as an Arazzo API specification

After authoring and generating the workflow, I exported it into an Arazzo API specification file and inspected the exported spec in the package explorer. The exported Arazzo spec contains a pictorial representation and the raw spec on the side for review. Crucially, the exported spec encodes the asynchronous send/receive pair for Kafka as well as the synchronous HTTP operations.

Step 3 — Prepare test input data

To run the Arazzo API spec workflow test, you need test data describing the journey inputs. I prepared a JSON input file containing multiple example journeys:

• A default (happy path) journey where the products array returned is non-empty and the order flow proceeds through Kafka and returns confirmation.
• A not-so-happy path where the products array is empty, causing the workflow to skip the asynchronous order creation and end early.

These inputs map to the paths defined in the Arazzo spec and allow the test runner to simulate different end-to-end scenarios in one run.

Step 4 — Run the Arazzo API spec workflow test

With the application running locally (in my case, Docker containers hosting the services) and the Arazzo spec plus input data ready, I ran the workflow test from Specmatic. The runner determines the target URLs and Kafka server info directly from the underlying OpenAPI and AsyncAPI specifications (via server URLs and broker configs embedded in those specs), so there’s no need to supply endpoints manually at run time.

The test run produced a visual trace showing the entire journey. For each step you can click and inspect the HTTP request/response or the message payloads exchanged on Kafka topics. That visual representation makes it easy to verify the sequence, the data conditions (e.g., non-empty arrays), and the final outcome for each input scenario.

Interpreting results: happy path vs. not-so-happy path

When tracing the default happy path in the Arazzo API spec workflow test I saw:

• Get user details returned 2xx and a non-empty products array.
• Create order sent a Kafka message (send) and later received a Kafka confirmation (receive).
• Get order details returned expected data and the workflow completed.

For the not-so-happy path, the products array was empty, so the workflow skipped the Kafka send/receive and ended at that decision point. The visual trace and the step-level logs make it easy to confirm the intended branching behavior.

Inspecting asynchronous steps

Asynchronous steps require careful attention: you must define the message payload schema, the topic to send to, and the expected reply topic and payload schema. In the Arazzo spec exported from the workflow:

• The create order step is encoded as a send operation to an order topic with a specific payload.
• The order confirmation step is encoded as a receive operation on a response topic with a confirmation payload schema.

During the test, Specmatic publishes the Kafka message and then listens for the expected confirmation message matching the schema. If the confirmation doesn’t arrive or doesn’t match, the step fails and the visual trace shows the failure details.

Best practices and tips

• Define servers and brokers in your OpenAPI/AsyncAPI specs: The runner extracts target endpoints from the specs, so ensure servers and broker info are kept up to date.
• Model decision logic clearly: Use simple data conditions (e.g., array length checks, HTTP status checks) so your workflow branches are easy to reason about.
• Validate message schemas: Ensure your AsyncAPI schemas are precise—matching on structure helps the runner detect and surface mismatches quickly.
• Keep test data representative: Include both happy and unhappy paths in your input set to validate all branches of the workflow.
• Use visual traces for debugging: The step-by-step diagram and step logs are the fastest way to find where an end-to-end flow diverges from expected behavior.

Recap: what we accomplished

By the end of the session we had done the following:

1. Taken simple OpenAPI and AsyncAPI specifications for services (location, products, order).
2. Authored a visual workflow that mixes synchronous and asynchronous operations and encodes decision points.
3. Exported that visual workflow into an Arazzo API specification.
4. Supplied test inputs that exercise both happy and alternate journeys.
5. Ran the Arazzo API spec workflow test against the running services to validate the end-to-end behavior and inspected the results through a visual trace.

This approach helps teams validate complex integration scenarios before they hit production, and it makes it straightforward to catch mismatches between API contracts and runtime behavior across both HTTP and message-based interactions.

FAQ

Q: What is an Arazzo API spec workflow test?

A: An Arazzo API spec workflow test is a test run derived from a workflow authored using operations from OpenAPI and AsyncAPI specifications. It exercises an end-to-end sequence of synchronous and asynchronous calls captured in the Arazzo spec, validating both messaging and HTTP interactions against live services.

Q: How does the runner know where to send HTTP requests and messages?

A: Server URLs for HTTP and broker information for messaging are taken directly from the OpenAPI and AsyncAPI specs. The test runner uses those server definitions when executing the steps in the Arazzo workflow.

Q: Can I test multiple journeys with one Arazzo spec?

A: Yes. Supply an input file with multiple examples (happy path and alternate scenarios). The runner will execute each journey and provide separate traces and logs for each.

Q: How are async send/receive pairs handled?

A: The Arazzo spec encodes send and receive steps for AsyncAPI operations. During test execution the runner sends the message to the configured topic and listens on the configured response topic for a matching message schema. The receive step can be validated by schema and content.

Q: What should I do if a receive step never gets a message?

A: Check that the service actually publishes to the expected topic and that broker configs are correct in the AsyncAPI spec. Use the trace logs to inspect sent payloads, and verify the consumer side can produce the confirmation message matching your schema.

Q: Can I extend this approach to other message systems besides Kafka?

A: Yes. AsyncAPI supports many brokers—Kafka, MQTT, AMQP, etc. As long as your AsyncAPI spec describes the broker and topics, the workflow can include send/receive operations against that broker type.

Final thoughts

Combining OpenAPI and AsyncAPI into a single Arazzo API spec workflow test gives you a concise, visual way to validate complex integration flows that mix HTTP and messaging. Author visually, export the Arazzo spec, provide realistic input journeys, and run the test to get an actionable visual trace of your system’s behavior. Try building one for a real scenario in your system—you’ll quickly see how much faster end-to-end diagnosis becomes.

If you want to repeat the exact steps I used, follow the flow above and remember: define servers/brokers in your API specs, include both happy and unhappy path inputs, and use the visual trace to pinpoint issues rapidly. Running an Arazzo API spec workflow test is one of the most effective ways to validate complex multi-protocol integration scenarios.