Generating OpenAPI Specifications for Publish Services

Overview

For services configured in the Publish direction (SOAP-to-REST), the platform automatically generates a standards-compliant OpenAPI v3 specification. This document serves as the canonical, machine-readable contract for the REST API endpoint that the platform exposes to API consumers.

The generated OpenAPI specification is not a generic template; it is a precise description of the live API endpoint, built from the source WSDL and the specific conversion settings applied to the service. It details every available path, the request and response schemas for each operation, and the potential error shapes. API consumers can use this document with standard tooling to generate client libraries, create mock servers, or run contract tests.

How it works

The OpenAPI specification is generated as a direct consequence of the publish action. The process synthesizes the service's configuration and source WSDL into a complete REST API definition.

flowchart TD
    subgraph "API Publisher Inputs"
        A[Source WSDL]
        B[Conversion Options]
    end

    subgraph "Platform"
        C(Publish Action)
        D{OpenAPI Generation}
    end

    subgraph "Outputs"
        E[REST Endpoint]
        F[OpenAPI v3 Specification]
    end

    A --> C
    B --> C
    C --> D
    D --> F
    D --> E

    style F fill:#e9f5e9,stroke:#333,stroke-width:2px
    style E fill:#e9f5e9,stroke:#333,stroke-width:2px

1. Trigger: Generation runs automatically when an API publisher publishes a service version.
2. Inputs: The process uses the active service version's configuration, including:
   • The source WSDL document.
   • The set of enabled operations.
   • All configured conversion options, such as field mappings and data type transformations.
   • WSDL-declared wsdl:fault contracts.
3. Processing: The platform constructs the OpenAPI document:
   • An API path is created for each enabled SOAP operation.
   • Request and response schemas are derived from the WSDL and modified by the configured field matching and validation rules.
   • The server URL (servers[0].url) is set to the service's runtime base path: /publish/{environment}/{serviceKey}.
   • Error responses for each operation are defined based on the corresponding wsdl:fault detail contracts from the WSDL.
4. Output: The resulting OpenAPI v3 document accurately describes the runtime behavior of the REST endpoint. The specification and the endpoint are always in sync, as they are generated from the same source configuration.

Reflection of Conversion Preferences

The generated OpenAPI schema is a direct reflection of the configured conversion options. Any change to these options will be present in the specification generated during the next publish event.

• Field Naming: The Field-name casing option renames properties in the JSON schemas.
• Data Types: Date/time, numeric, boolean, duration, and binary options determine the type and format of schema fields.
• Nullability: The Null / empty handling configuration is reflected in a field's nullability within the schema.
• Response Structure: The Response envelope wrap and JSON field ordering options shape the structure of the response body schema.
• Validation: Validation regexes are emitted as pattern constraints on string fields. Integer range bounds are emitted as minimum and maximum constraints on integer fields.
• Error Shape: The Error / fault shape option determines the schema for error responses, such as one conforming to RFC 7807 Problem Details.
• Upstream Status Handling: The Upstream-failure-status setting is surfaced via the extension keys x-s2r-upstream-failure-status and x-s2r-failure-body-in-200.

Per-Operation Fault Schemas

The platform inspects the source WSDL for wsdl:fault definitions associated with each operation. These are translated into distinct error responses in the OpenAPI document, allowing API consumers to understand the specific fault structures for each operation before making a call.

Reviewing and Using the OpenAPI Specification

After a service is published, its OpenAPI specification is made available in both JSON and YAML formats. It can be accessed via a direct URL or downloaded from the service's page in the user interface.

API publishers can provide the specification URL and the service base URL to API consumers, who can then import the document into their preferred development and testing tools.

Refining the Specification

Before or after the first publish, API publishers can refine the generated specification by making edits in the Mapping tab of the service configuration. Common refinements include:

• Operation Summaries: Improving the human-readability of operation names (e.g., changing getCustomerByIdRequest to a descriptive summary).
• Examples: Replacing placeholder examples with realistic request and response payloads. The platform may also suggest examples based on observed production traffic via the learned examples feature.
• Field Descriptions: Adding hints, format descriptions, and other clarifying text to schema fields. UTF-8 and right-to-left (RTL) text are supported.

Each set of edits creates a new, immutable revision of the service.

Troubleshooting

OpenAPI Generation for Consume Services

• Condition: An attempt is made to generate an OpenAPI specification for a service configured with the Consume direction.
• Trigger: This is an invalid operation, as Consume services expose a WSDL contract to their consumers, not a REST/OpenAPI contract.
• Resolution: The platform rejects the request with an error message indicating that OpenAPI generation is not applicable to Consume services. This prevents the creation of a misleading artifact.

See Also

• Publish & version a service
• Conversion options reference
• Consume direction

All SOAP-to-REST docs