OpenAPI Artifact Repository

Overview

The OpenAPI Repository is a data access component responsible for the persistence and retrieval of OpenAPI specifications. It serves as the bridge between the database and the OpenAPI generator. Its primary role is to supply the generator with all the necessary data to construct a service version's OpenAPI specification, including service metadata, enabled operations, and a wide array of fine-grained configuration overrides.

The repository fetches data from several database tables to assemble a complete picture of a service version. This includes:

• Core service and version details.
• A list of all enabled operations for the version.
• Extensive operation-level and per-field overrides that control the generated REST/JSON interface, such as data type mapping, null handling, and error shapes.
• WSDL-defined SOAP fault and header contracts, which are merged into the OpenAPI specification to represent custom error responses and required headers.

After the OpenAPI generator produces a specification, the repository is used to store the resulting artifact in the database, linking it to the specific service version.

How it Works

The OpenAPI Repository interacts with the database to gather all configuration and metadata for a given service version. The OpenAPI generator calls the repository's methods to fetch this data before constructing the specification.

The process flow is as follows:

1. Fetch Service Metadata: The generator first calls findServiceVersion to retrieve basic information about the service version, such as its name, key, and environment.
2. Fetch Operation Details: The generator then calls findEnabledOperations to get a detailed OperationSnapshot for every enabled operation in the service version. This is the most complex query, joining s2r_operation with s2r_operation_mapping to collect dozens of configuration overrides that influence the final OpenAPI specification.
3. Fetch WSDL Contracts: To include SOAP-specific details, the generator makes separate calls to findOperationFaults and findOperationHeaders. These methods retrieve WSDL-defined fault contracts and SOAP headers, respectively. This data is kept separate from the main OperationSnapshot for architectural reasons but is merged by the generator to produce accurate error responses and header definitions.
4. Generate Specification: With all the necessary data, the OpenAPI generator constructs the OpenAPI JSON document.
5. Store Artifact: The generator calls upsertArtifact to save the newly created OpenAPI JSON to the s2r_openapi_artifact table. This method also updates the s2r_service_version table with the artifact's SHA256 hash and generation timestamp in a single transaction.

The repository is designed to be schema-defensive. If optional data like operation faults, headers, or specific override columns are missing from the database (e.g., in older schemas), the repository returns empty collections instead of failing. This allows the OpenAPI generator to proceed with sensible defaults, ensuring backward compatibility.

flowchart TD
    subgraph OpenAPI Generation Process
        A[OpenAPI Generator]
    end

    subgraph Data Persistence
        DB[(Database)]
        T1[s2r_service_version]
        T2[s2r_operation]
        T3[s2r_operation_mapping]
        T4[s2r_wsdl_operation_catalog]
        T5[s2r_openapi_artifact]

        DB --- T1 & T2 & T3 & T4 & T5
    end

    subgraph Admin API
        Repo[OpenAPI Repository]
    end

    A -- "1. Fetch metadata" --> Repo
    Repo -- "findServiceVersion, findEnabledOperations, etc." --> DB
    DB -- "Snapshots, Overrides, Faults, Headers" --> Repo
    Repo -- "2. Return data models" --> A
    A -- "3. Generate OpenAPI JSON" --> A
    A -- "4. Store artifact" --> Repo
    Repo -- "upsertArtifact" --> DB

API Reference

The OpenApiRepository class provides the following public methods for interacting with the database.

upsertArtifact Parameters

Data Models

The repository returns data in several structured record types.

ServiceVersionSnapshot

Contains high-level metadata about a specific service version.

OperationSnapshot

A comprehensive record containing all configuration for a single operation. This data directly drives how the OpenAPI specification is generated for that operation. Fields are typically either an operation-level override (a String) or a map of per-field overrides (Map<String, ...>), where the key is a SOAP XPath. If an override is not set (null), the system default is used.

Null Handling

Data Type Handling

Structural & Semantic Handling

OpenApiArtifactRecord

Represents a stored OpenAPI specification artifact.

Example: Storing an Artifact

The upsertArtifact method performs a transactional database update to store a new OpenAPI specification. It executes two main SQL operations:

1. Upsert the Artifact: It inserts a new record into the s2r_openapi_artifact table. If a record for the service_version_id already exists, it updates the existing record with the new content. This is achieved using an ON CONFLICT clause.

   insert into s2r_openapi_artifact (
       id, service_id, service_version_id, openapi_json, sha256, generated_at, generated_by
   )
   values (?, ?, ?, ?, ?, ?, ?)
   on conflict (service_version_id) do update
      set service_id = excluded.service_id,
          openapi_json = excluded.openapi_json,
          sha256 = excluded.sha256,
          generated_at = excluded.generated_at,
          generated_by = excluded.generated_by
   

2. Update the Service Version: It updates the s2r_service_version table to record the sha256 and generated_at timestamp of the newly stored artifact, linking the version to its current specification.

   update s2r_service_version
   set openapi_sha256 = ?,
       openapi_generated_at = ?
   where id = ? and service_id = ?
   

These two operations are wrapped in a transaction to ensure data consistency.

Troubleshooting

The repository is designed with resilience to prevent failures during OpenAPI generation due to missing or malformed data.

• Missing WSDL Faults/Headers: If a service version was created with an older schema that lacks the operation_faults or operation_headers columns, the findOperationFaults and findOperationHeaders methods will catch the resulting RuntimeException. They will log the error internally and return an empty Map. This allows spec generation to continue, falling back to generic error shapes and no custom headers, rather than failing completely.

• Malformed JSON in Database: The helper methods (parseStringMap, parseObjectMap) that deserialize JSONB columns are wrapped in try-catch blocks. If the JSON content is null, blank, or syntactically incorrect, the method returns an empty Map or List. This isolates data corruption issues to a specific field's configuration and prevents it from halting the entire process.

• Not Found Errors: Methods like findServiceVersion and findArtifact return an Optional. If the requested serviceId and versionId do not correspond to an existing record, the Optional will be empty. The calling code must handle this case and not assume a record will always be found.

All SOAP-to-REST docs