WSDL Import Preview and Example Generation

Overview

The ContractExampleService is a backend component that processes the results of a WSDL import to generate a comprehensive preview for an API publisher. Its primary function is to analyze each operation within a parsed WSDL, suggest a corresponding REST API structure, generate sample request and response payloads, and assess the complexity of automatically transforming the SOAP operation into a RESTful one.

This service solves the problem of understanding a complex WSDL file in the context of a REST-to-SOAP gateway. Instead of requiring manual inspection of the WSDL, it produces a structured report that includes:

• Suggested REST routes and methods for each SOAP operation.
• Example payloads for both the original SOAP backend and the suggested REST facade.
• A complexity score (zeroTouchScore) and review state (reviewState) to guide the onboarding process.
• Detailed notes and flags highlighting potential complexities like xsd:choice or xsd:any.

The service is called after a WSDL file has been successfully imported and parsed into a WsdlImportResult object. It uses this object, along with heuristics and other services, to build the preview, which is then typically used to populate a user interface for API publishers to review and configure their new API.

How it works

The ContractExampleService generates a preview by orchestrating several analysis and generation steps. The main entry point is the buildImportPreview method.

flowchart TD
    subgraph Input
        A[WsdlImportResult]
        B(WsdlImportComparisonRecord <br/>- optional)
    end

    subgraph "ContractExampleService.buildImportPreview"
        C[Get Draft Suggestions]
        D{For each WSDL Operation}
        E[Infer REST Route]
        F[Inspect Route for Parameters]
        G[Build Operation Preview]
        H[Aggregate Summary Statistics]
    end

    subgraph "Operation Preview Generation"
        G --> G1[Analyze Schema Complexity]
        G --> G2[Calculate 'zeroTouchScore']
        G --> G3[Determine 'reviewState']
        G --> G4[Generate Example Payloads <br/>- SOAP & JSON <br/>- Minimal & Rich]
        G --> G5[Build Example REST URL]
    end

    subgraph Output
        I[Final Import Preview]
    end

    A --> C
    A --> D
    B --> D
    C --> E
    D --> E
    E --> F
    F --> G
    D -- operation data --> G
    G --> H
    H --> I

Import Preview Generation Flow

1. Receive Import Data: The process starts when buildImportPreview is called with a WsdlImportResult and an optional WsdlImportComparisonRecord (for showing changes from a previous version).
2. Get Draft Suggestions: It calls the OnboardingDraftSuggestionService to get baseline suggestions for the service, such as a proposed serviceKey.
3. Iterate Operations: The service iterates through each WsdlOperationRecord found in the import result.
4. Infer REST Route: For each operation, WsdlRestRouteHeuristics.inferRoute is used to propose a REST method (e.g., POST) and path (e.g., /v1/myservice/get-user). This process tracks used routes to detect and resolve collisions.
5. Inspect Route: The proposed route is then analyzed by WsdlRestRouteHeuristics.inspectRoute to identify which fields from the request schema are good candidates to become REST path parameters, query parameters, or body fields.
6. Build Operation Preview: The core logic resides in buildOperationPreview, which assembles a detailed report for the single operation. This involves:
   • Collecting Complexity Flags: It inspects the request and response schemas for complex XSD constructs like choice, wildcard (xsd:any), polymorphic types (xsi:type), and attribute usage.
   • Scoring and State Assessment: It calculates a zeroTouchScore from 100 down, penalizing for each complexity flag found. Based on this score, it assigns a reviewState: READY_FOR_ZERO_TOUCH (score >= 90), READY_WITH_REVIEW (score >= 70), or COMPLEX_REVIEW.
   • Generating Payloads: It generates multiple example payloads by recursively traversing the contract schema. This includes minimal and rich JSON samples, corresponding SOAP envelopes, and a "round-trip" payload created by parsing the generated SOAP response.
   • Building Example URL: An example REST URL is constructed by populating path and query parameter placeholders in the suggested REST path with values from the rich example payload.
7. Aggregate and Finalize: After processing all operations, the service aggregates summary statistics (e.g., counts of operations in each reviewState) and combines them with import metadata and the list of individual operation previews into a single map structure, which is the final output.

Example Payload Generation

Example values are generated by the generateRequestSample and generateResponseSample methods, which recursively render the contract schema.

• Flavors: Generation supports two flavors, defined by the ExampleFlavor enum:
  • MINIMAL: Includes only required fields.
  • RICH: Includes required and a selection of optional fields.
• Value Sampling: The sampleScalar method generates a value based on the field's XSD type and name.
  • Heuristics: It uses name-based heuristics (via nameHasToken) to generate realistic samples for fields named email, phone, url, etc. This matching is token-aware to prevent matching substrings within words.
  • Numeric Constraints: For numeric types, it respects min/maxInclusive/Exclusive, totalDigits, and fractionDigits facets. It generates whole numbers for fields that appear to be integers by name (e.g., orderId) or schema (fractionDigits=0).
  • String Constraints: For strings, it uses ConstrainedStringSampler to generate values that conform to pattern, minLength, and maxLength facets.
  • Pattern-based Generation: If a field has an xsd:pattern, the service uses RegexExampleGenerator to create a matching example string. This is crucial for fields like numeric dates (YYYYMMDD) that are typed as integers but have a strict format.

API Reference

The ContractExampleService exposes several public methods for generating previews and examples.

public Map<String, Object> buildImportPreview(WsdlImportResult result, WsdlImportComparisonRecord comparison) : The main entry point. Generates a full import preview for all operations in a WsdlImportResult. An optional WsdlImportComparisonRecord can be provided to include diff information.

public Map<String, Object> buildOperationPreview(WsdlOperationRecord operation, ...) : Generates a detailed preview for a single WsdlOperationRecord. This is primarily called by buildImportPreview.

public Object generateRequestSample(Map<String, Object> contract, ExampleFlavor flavor) : Generates a sample JSON request payload from a contract schema map. The flavor determines whether to include only required fields (MINIMAL) or optional fields as well (RICH).

public Object generateResponseSample(Map<String, Object> contract) : Generates a RICH sample JSON response payload from a contract schema map.

public List<Map<String, Object>> describeRequestFields(Map<String, Object> contract, ExampleFlavor flavor) : Flattens a request contract schema into a list of field descriptors, including path, type, constraints, and an example value.

Return Value Structure

The buildImportPreview method returns a Map<String, Object> with a detailed, nested structure.

Top-Level Fields

Summary Object

The summary object provides a high-level overview of the import analysis.

Operation Preview Object

Each object in the operations list provides a detailed analysis of a single WSDL operation.

Troubleshooting

While the service is designed to be robust, the complexity of WSDL and XSD schemas can lead to issues in the generated preview.

• Empty Payloads or Envelopes: If the service encounters an unrecoverable error during payload or SOAP envelope generation (e.g., due to a malformed contract), it will return an empty string or empty map for the affected field rather than failing the entire process. This isolates failures to the specific example.
• Incorrect Example Values: An example value in the preview might be invalid if the schema contains complex, co-dependent constraints that the generator does not fully model. The source code contains comments indicating several scenarios that have been addressed and may point to the types of issues to look for:
  • A numeric field (e.g., xsd:int) receives a string example (e.g., a URL) because its name contains a keyword like "uri". The current implementation avoids this by checking the field's type before applying name-based heuristics.
  • A numeric example violates a totalDigits constraint. The generator now attempts to clamp the value to fit within the specified number of significant digits.
  • A numeric example violates a pattern constraint (e.g., an xsd:int field requiring YYYYMMDD format). The generator now prioritizes creating an example from the pattern.
  • A string example violates a pattern that is intended as a character allow-list with a maxLength. The pattern validator has a fallback to treat such patterns as per-character rules rather than a strict full-string match.

If a generated example appears incorrect, the first step is to review the requestSchema and responseSchema objects in the preview output and compare them against the original WSDL/XSD source to verify that all constraints (pattern, maxLength, totalDigits, etc.) were correctly interpreted.

See Also

• OnboardingDraftSuggestionService: Provides initial suggestions for API configuration.
• SoapMessageMapper: Handles the conversion between JSON payloads and SOAP 1.1 envelopes.
• WsdlRestRouteHeuristics: Implements the logic for inferring REST routes from WSDL operations.
• ConstrainedStringSampler: Generates string examples that conform to XSD length and pattern facets.
• RegexExampleGenerator: Creates example strings that match a given regular expression.
• ContractPatternValidator: Provides the canonical implementation for validating values against XSD patterns.

All SOAP-to-REST docs