Generate & review the OpenAPI

For a Publish service the platform emits a standards-compliant OpenAPI v3 document that describes the REST contract consumers call.

For a Publish service the platform emits a standards-compliant OpenAPI v3 document that describes the REST contract consumers call. This page covers what's generated, how your conversion options shape it, and how to consume it.

Consume (SOAP-facade) services do not get a generated OpenAPI document — their consumer-facing contract is SOAP, served back as WSDL. See Consume direction. Asking to generate OpenAPI for a Consume service is not applicable and is rejected with a clear error rather than producing a misleading artifact.

When generation runs

OpenAPI generation runs at publish. The emitted document is built from the active service version: one path per enabled operation, request/response schemas derived from the WSDL and your field-match and validation configuration, servers[0].url pointing at the service's /publish/{environment}/{serviceKey} runtime base, and per-operation error responses derived from the WSDL-declared wsdl:fault detail contracts.

The artifact is a faithful, machine-readable spec of a real REST endpoint — it accurately describes the contract REST clients call on the publish facade.

How your conversion preferences are reflected

The generated schema mirrors your conversion options so the published contract always matches the runtime behavior. For example:

Field-name casing renames the schema properties.
Date/time, numeric, boolean, duration, and binary options shape the field types/formats.
Null / empty handling is reflected in nullability.
Response envelope wrap and JSON field ordering shape the response body schema.
Validation regexes are emitted as schema pattern constraints; integer range bounds emit or omit minimum/maximum on integer fields.
Error / fault shape determines the error-response schema (e.g. RFC 7807 Problem Details).
Upstream-failure-status surfaces as the extension keys x-s2r-upstream-failure-status and x-s2r-failure-body-in-200.

Change an option and regenerate, and both the runtime and the spec move together. See How mapping works.

Per-operation fault schemas

Each operation's WSDL-declared wsdl:fault detail contracts are emitted as per-operation error responses in the OpenAPI document. Consumers can see the shape of a fault — under your chosen error shape — before they ever hit one. See SOAP & XSD support → Faults.

Reviewing & importing into tools

After publish the spec is served per service (JSON and YAML), and is also downloadable from the service's page in the UI. Point consumers at the OpenAPI URL and the service base URL; they can import the document into their preferred API tooling to generate clients, mock servers, or contract tests.

Common edits operators make before/after first publish, in the Mapping tab:

Display names / summaries — turn getCustomerByIdRequest into a readable operation summary.
Examples — replace placeholder examples with realistic ones; where production traffic exists, learned examples suggest real values.
Field hints & descriptions — formats and locale strings (UTF-8 / RTL supported).

Each edit creates a new immutable revision — see Publish & version a service.

Next reads

Publish & version a service — the readiness gate and versioning.
Conversion options reference — what shapes the schema.
Consume direction — WSDL serve-back instead of OpenAPI.

All Specaria SOAP to REST docs

Loading…