OpenAPI Specification Data Repository

# OpenAPI Specification Data Repository

## Overview

The OpenAPI Specification Data Repository is a data access component responsible for managing the persistence and retrieval of generated OpenAPI specifications and their associated metadata. It serves as the bridge between the database and higher-level services, such as an OpenAPI specification generator.

This component solves two primary problems:
1.  **Data Aggregation for Spec Generation**: It gathers all necessary information about a service version—including its enabled operations, REST-to-SOAP mappings, data transformation rules, and WSDL-defined metadata—into structured data snapshots.
2.  **Artifact Persistence**: It stores the final, generated OpenAPI JSON documents in the database, associating them with a specific service version and tracking their content hash and generation metadata.

It is primarily called by an internal OpenAPI generator service. The repository's methods query multiple database tables to assemble a complete picture of a service version, which is then used to produce a compliant OpenAPI specification.

## How it Works

The repository's functionality can be divided into data retrieval for specification generation and the persistence of the resulting artifact.

### Data Retrieval for Specification Generation

To generate an OpenAPI specification for a given service version, a consumer of this repository typically follows this sequence:

1.  **Fetch Service Version Details**: Call `findServiceVersion` to retrieve basic metadata about the service and version, such as its name, key, and environment.
2.  **Fetch Enabled Operations**: Call `findEnabledOperations` to get a detailed `OperationSnapshot` for every enabled operation in that version. This is the most complex query, joining data from `s2r_operation` and `s2r_operation_mapping` to consolidate not only the REST path and method but also a wide array of fine-grained data transformation and behavior overrides.
3.  **Fetch Ancillary WSDL Metadata**: Make separate calls to `findOperationFaults` and `findOperationHeaders` to retrieve WSDL-declared `wsdl:fault` and `soap:header` definitions, respectively. This data is intentionally kept separate from the main `OperationSnapshot` to simplify the data model.
4.  **Merge and Generate**: The calling service is responsible for merging the data from these separate calls. For example, the custom fault information from `findOperationFaults` is merged with the corresponding `OperationSnapshot` (keyed by `soap_operation_name`) to generate per-operation error responses in the final OpenAPI specification.

The following diagram illustrates this data flow:

```mermaid
flowchart TD
    subgraph OpenAPI Generator
        A[Initiate Spec Generation]
    end

    subgraph Data Repository
        B[findServiceVersion]
        C[findEnabledOperations]
        D[findOperationFaults]
        E[findOperationHeaders]
    end

    subgraph Database
        F[s2r_service, s2r_service_version]
        G[s2r_operation, s2r_operation_mapping]
        H[s2r_wsdl_operation_catalog]
        I[s2r_operation]
    end

    subgraph Merging Logic
        J[Merge Data Snapshots]
    end

    subgraph Output
        K[Generate OpenAPI Spec]
    end

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

    B --> F
    C --> G
    D --> H
    E --> I

    B -- ServiceVersionSnapshot --> J
    C -- List<OperationSnapshot> --> J
    D -- Map<String, List<WsdlOperationFaultRecord>> --> J
    E -- Map<String, List<WsdlOperationHeaderRecord>> --> J

    J --> K

Artifact Persistence

Once an OpenAPI specification is generated, it is persisted using the upsertArtifact method. This method performs a transactional update:

1. It inserts or updates a record in the s2r_openapi_artifact table. This record contains the full OpenAPI JSON content, its SHA256 hash, and metadata about who (actor) and when (generatedAt) it was generated. If a record for the service_version_id already exists, it is updated in place.
2. It then updates the corresponding record in the s2r_service_version table to store the openapi_sha256 and openapi_generated_at timestamp, ensuring the service version is directly linked to its latest specification artifact.

Data Parsing and Error Handling

The repository is designed to be robust and schema-defensive to prevent failures in specification generation.

• Malformed JSON: Helper methods like parseStringMap and parseObjectMap are used to parse JSONB columns from the database. If the JSON content is null, blank, or malformed, these methods return an empty map instead of throwing an exception. This ensures that spec generation can proceed using default behaviors.
• Legacy Database Schemas: The methods for fetching WSDL-defined faults (findOperationFaults) and headers (findOperationHeaders) are wrapped in try-catch blocks. If a query fails (e.g., because the database schema predates the required columns like operation_faults), it returns an empty map. This allows the system to function correctly with older database schemas, simply omitting the features that depend on the missing columns.

API Reference

The repository exposes several public methods for interacting with the database.

| Method | Description - | findServiceVersion(serviceId, versionId) | Retrieves a ServiceVersionSnapshot containing metadata for a specific service version. Returns an empty Optional if not found. - | findEnabledOperations(versionId) | Returns a list of OperationSnapshot records for all enabled operations within a service version. This is the primary method for gathering data for spec generation. - | findOperationFaults(versionId) | Retrieves WSDL-declared fault details for all operations in a service version, keyed by SOAP operation name. Returns an empty map if no faults are defined or if the schema is from a legacy version. - | findOperationHeaders(versionId) | Retrieves WSDL-declared SOAP header details for all enabled operations in a service version, keyed by SOAP operation name. Returns an empty map if no headers are defined or if the schema is from a legacy version. - s| upsertArtifact(...) | Atomically inserts or updates an OpenAPI specification artifact in the s2r_openapi_artifact table and updates the s2r_service_version table with the artifact's hash and generation time. - | findArtifact(serviceId, versionId) | Retrieves a complete OpenApiArtifactRecord, including the full JSON content, for a specific service version. a- | listAllArtifactKeys() | Lists the serviceId and serviceVersionId for all stored OpenAPI artifacts. - | listArtifactVersionIdsForCurrentTenant() | Lists the serviceVersionIds for all artifacts belonging to the current tenant. This is used for internal reconciliation tasks. - | findArtifactByVersion(versionId) | Retrieves a complete OpenApiArtifactRecord for a specific service version, scoped to the current tenant. -

Data Structures

The repository returns data in several key record types.

ServiceVersionSnapshot

This record provides high-level metadata about a service version.

| Field | Type | Description - | serviceId | UUID | The unique identifier of the service. - | serviceVersionId | UUID | The unique identifier of the service version. -

| versionNo | integer| The version number. - | serviceKey | String | A unique string key for the service. - | serviceName | String | The human-readable name of the service. - | environment | String | The deployment environment (e.g., "development", "production"). - | description | String | A description of the service. - | direction | String | The service direction (e.g., PUBLISH, GATEWAY). The value is normalized to a standard set. -

OperationSnapshot

This record contains an exhaustive set of properties for a single operation, used to drive the generation of its OpenAPI representation. Many fields are overrides that allow fine-tuning behavior at the operation or field level, inheriting from system-wide defaults if not set.

| Field | Type | Description - | operationKey | String | A unique string key for the operation. - | soapOperationName | String | The name of the SOAP operation as defined in the WSDL. - | soapAction | String | The SOAPAction HTTP header value associated with the operation. - | restMethod | String | The HTTP method (e.g., GET, POST) for the generated REST endpoint.

---

All SOAP-to-REST docs