Generating OpenAPI Specs from Visual UI Interaction Logs: The Enterprise Guide to Reverse Engineering Legacy APIs

Stop trying to read 15-year-old Java code to find an endpoint. It is a waste of your engineering talent. In the enterprise world, the UI is often the only source of truth that hasn't lied to you. While backend documentation rots and developers leave, the interface remains the functional contract between the user and the system. If a button works in production, the underlying API call—no matter how undocumented—is alive.

The challenge for most architects is that $3.6 trillion in global technical debt isn't just sitting in code; it's hidden in the "black box" of network traffic. Manually mapping these calls to create documentation is an exercise in futility. Industry experts recommend a shift toward automated discovery, and that starts with generating openapi specs from visual UI interaction logs.

TL;DR: Manual API documentation is the bottleneck of legacy modernization. By using Replay to record user workflows, architects can automatically extract network traffic and transform it into valid OpenAPI 3.0 specifications. This approach reduces documentation time by 90%, turning a 40-hour manual audit into a 4-hour automated process.

---

The Documentation Gap: Why Manual Discovery Fails#

According to Replay's analysis, 67% of legacy systems lack any form of usable API documentation. When an enterprise decides to modernize, the first 6 months are typically spent in "discovery hell"—developers using Chrome DevTools to click every button, copy JSON payloads, and manually paste them into Swagger editors.

This manual approach is prone to "Schema Drift," where the documentation reflects what the developer thinks the API does, rather than what it actually does. Visual Reverse Engineering is the process of using recorded user interactions to reconstruct the underlying software architecture, including UI components, state logic, and API contracts.

By generating openapi specs from real-world interaction logs, you capture the edge cases that manual documentation misses: the 500 errors on specific input strings, the undocumented headers required for authentication, and the polymorphic JSON responses that change based on user roles.

---

The Architecture of Generating OpenAPI Specs from Visual Logs#

To move from a video recording to a functional API specification, we need a pipeline that bridges the gap between the DOM and the Network Layer. Replay facilitates this through its "Flows" and "AI Automation Suite."

1. Recording the Interaction (The "Flow")#

The process begins by recording a real user workflow. As the user interacts with the legacy UI, Replay's engine captures not just the visual changes, but the full telemetry of the browser. This includes:

• •DOM mutations
• •XHR/Fetch requests and responses
• •Request headers and payload structures
• •Timing and latency data

2. Traffic Interception and Normalization#

Once the flow is recorded, the data is processed. Raw JSON payloads are often messy. Generating openapi specs from these logs requires a normalization layer that identifies patterns. For example, if three different clicks call

, the engine must recognize the path parameter rather than creating three separate endpoints.

3. Schema Inference#

This is where the heavy lifting happens. The system analyzes the JSON body to infer types (string, integer, boolean, null) and required fields.

Definition Block: Schema Inference is the algorithmic process of determining the data structure and validation rules of an API by analyzing its historical request and response payloads.

typescript
// Example: A legacy API response captured by Replay
interface LegacyUserResponse {
  user_id: number;
  full_name: string;
  is_active: 0 | 1; // Legacy boolean as integer
  metadata: {
    last_login: string; // ISO Date
    permissions: string[];
  };
}

// Replay transforms this into a standardized React hook and 
// prepares the data for OpenAPI generation.
export const useLegacyUser = (id: string) => {
  return useQuery(['user', id], async () => {
    const response = await fetch(`/api/v1/users/${id}`);
    return response.json() as LegacyUserResponse;
  });
};

---

Technical Challenges in Generating OpenAPI Specs from Legacy Traffic#

While the concept is straightforward, generating openapi specs from legacy traffic involves navigating several technical hurdles. Legacy systems rarely follow modern REST conventions. You will encounter:

• •SOAP/XML Wrappers: APIs that return XML inside a JSON string.
• •Non-Standard Status Codes: Systems that return
  text

  200 OK
  for every request, even when the body contains an error message.
• •Dynamic Keys: JSON objects where the keys are IDs rather than property names.

Overcoming Data Polymorphism#

One of the biggest hurdles in generating openapi specs from interaction logs is polymorphism. A

endpoint might return a object in one flow and a object in another. Replay’s AI Automation Suite compares multiple recordings of the same endpoint to build a "OneOf" or "AnyOf" schema in the resulting OpenAPI document.

Security and PII Masking#

In regulated industries like Healthcare and Financial Services, interaction logs contain sensitive data. Replay is built for these environments (SOC2, HIPAA-ready). Before the OpenAPI spec is generated, the system runs a PII (Personally Identifiable Information) masking layer. This ensures that while the structure of the API is captured, the data (SSNs, Credit Card numbers) is never stored or included in the documentation.

Learn more about Modernizing Regulated Systems

---

Step-by-Step Guide: From Recording to OpenAPI#

If you are tasked with documenting a legacy system, follow this practical workflow using Replay.

Step 1: Record the "Golden Path"#

Open the Replay browser extension and record the most critical user workflows. For a banking app, this might be "Login -> View Balance -> Transfer Funds -> Logout."

Step 2: Extract the "Flows"#

Replay's Flows feature visualizes the architecture of the recording. It maps the UI components to the network calls they trigger. This provides the context needed for the OpenAPI

and fields.

Step 3: Generate the Specification#

Using the Replay Blueprints editor, you can export the captured network traffic. The system automatically handles the conversion to YAML.

yaml
# Generated by Replay Visual Reverse Engineering
openapi: 3.0.3
info:
  title: Legacy Banking API
  version: 1.0.0
paths:
  /api/v1/transfer:
    post:
      summary: Transfer Funds
      description: Captured from "Transfer Funds" flow in Replay
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                from_account:
                  type: string
                  example: "ACC-12345"
                to_account:
                  type: string
                amount:
                  type: number
      responses:
        '200':
          description: Successful transfer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferResponse'

Step 4: Validate and Refine#

No automated tool is 100% perfect on the first pass. Replay allows you to refine the generated spec within the platform before pushing it to your repository. This is where you add human-readable descriptions and refine the Design System components that consume these APIs.

---

The Business Impact: 70% Time Savings#

The traditional enterprise rewrite timeline is 18–24 months. Much of this time is wasted on "Archaeology"—digging through old code to understand how the system works. Generating openapi specs from UI logs flips the script. Instead of reading the past, you are documenting the present.

According to Replay's internal benchmarks:

• •Phase 1 (Discovery): Reduced from 4 months to 2 weeks.
• •Phase 2 (Documentation): Reduced from 6 months to 3 weeks.
• •Phase 3 (Implementation): Accelerated by having ready-to-use React components and API mocks.

By using Replay, teams can modernize without rewriting from scratch. You aren't just getting documentation; you are getting a functional bridge to a modern React-based architecture.

Read about our 70% time savings case study

---

Integrating OpenAPI into your Modernization Stack#

Once you have succeeded in generating openapi specs from your legacy system, what’s next? The spec becomes the foundation for your new frontend.

1. •Mock Servers: Use the OpenAPI spec to spin up Prism or MSW (Mock Service Worker) servers. This allows frontend developers to build the new React UI in parallel with backend refactoring.
2. •Type Generation: Use tools like
   text

   openapi-typescript
   to generate high-fidelity TypeScript interfaces directly from the Replay output.
3. •Contract Testing: Use the spec to ensure that as you refactor the legacy backend into microservices, the API remains compatible with the UI.

Example: Consuming the Generated Spec in React#

When Replay generates your Component Library, it aligns the component props with the API schema it discovered.

tsx
import React from 'react';
import { useTransferFunds } from './api/generated'; // Generated from Replay OpenAPI spec

export const TransferForm: React.FC = () => {
  const { mutate, isLoading } = useTransferFunds();

  const handleTransfer = (data: TransferRequest) => {
    mutate(data);
  };

  return (
    <div className="p-4 border rounded-lg shadow-sm">
      <h2 className="text-xl font-bold">Transfer Funds</h2>
      {/* Replay-generated UI components based on legacy styles */}
      <LegacyInput name="from_account" label="Source Account" />
      <LegacyInput name="to_account" label="Destination" />
      <LegacyButton 
        onClick={handleTransfer} 
        disabled={isLoading}
      >
        Confirm Transfer
      </LegacyButton>
    </div>
  );
};

---

Frequently Asked Questions#

Can I generate OpenAPI specs from authenticated sessions?#

Yes. Replay captures the network traffic within the context of the user session. It records the necessary headers (like Bearer tokens or Cookies) to understand the request structure, though it allows you to strip or mask sensitive token values during the export process to maintain security compliance.

Does Replay support SOAP to REST conversion?#

While Replay captures the raw traffic (including XML/SOAP), its AI Automation Suite is specifically designed to help map those legacy payloads into modern JSON-based OpenAPI specifications. It identifies the core data structures within the XML and suggests a RESTful path structure for your new architecture.

How does this handle dynamic URL parameters?#

Replay’s inference engine analyzes multiple requests to the same base path. If it sees

, , and , it intelligently identifies that is a path parameter rather than creating three separate endpoints in your OpenAPI document.

What happens if my legacy UI is a "Single Page App" with no URL changes?#

Replay doesn't rely on URL changes to define "Flows." It monitors state changes, DOM mutations, and network triggers. Even in a complex, single-page legacy dashboard, Replay can segment different functional "Flows" based on user intent and interaction patterns.

---

Final Thoughts: Documentation as a Byproduct, Not a Chore#

The era of manual API documentation is over. In a world where $3.6 trillion is locked in technical debt, we cannot afford to have our best engineers spending 40 hours per screen just to understand how a legacy system communicates.

Generating openapi specs from visual UI interaction logs transforms documentation from a chore into a byproduct of the discovery process. With Replay, you capture the reality of your system, create a roadmap for modernization, and save 70% of the time usually lost to manual reverse engineering.

Ready to modernize without rewriting? Book a pilot with Replay