OpenAPI Artifact Repository

Overview

The OpenAPI Repository is a data access component responsible for the persistence and retrieval of OpenAPI specification artifacts. It serves as the interface between the platform's administrative services and the underlying database tables that store service configuration and generated OpenAPI documents.

This component solves the problem of centralizing data access for the OpenAPI generation process. When the platform generates an OpenAPI specification for a service version, it requires a comprehensive snapshot of all enabled operations and their extensive configuration overrides. The repository provides methods to query this data efficiently. It also handles the transactional insertion and updating (upsert) of the final generated OpenAPI JSON artifact, linking it to the corresponding service version.

The primary consumer of this repository is the platform's OpenAPI generator. The generator calls methods like findEnabledOperations, findOperationFaults, and findOperationHeaders to gather all necessary inputs. After generating the specification, it calls upsertArtifact to store the result in the s2r_openapi_artifact table.

How it works

The repository's main function is to aggregate all configuration data related to a service version and its operations, and to persist the generated OpenAPI artifact.

Data Aggregation for Spec Generation

To generate an OpenAPI specification, the generator requires a complete picture of the service. The repository provides several methods to build this picture by querying multiple database tables. The data is intentionally fetched in separate, targeted queries to keep data structures manageable and to ensure backward compatibility with older database schemas.

The process follows these steps:

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 core data is retrieved via findEnabledOperations. This method executes a complex query that joins the s2r_operation and s2r_operation_mapping tables. It gathers all enabled operations for a version and includes a wide array of operation-level and field-level configuration overrides. These overrides control behaviors like data type transformations, null handling, error shaping, and more. The result is a list of OperationSnapshot records.
3. Fetch Custom Faults: The generator calls findOperationFaults to load WSDL-defined SOAP fault structures from the s2r_wsdl_operation_catalog table. This data is keyed by the SOAP operation name and allows the generator to create specific error response schemas for each operation, rather than a single generic one. This query is separate from findEnabledOperations to avoid complicating the OperationSnapshot record.
4. Fetch Custom Headers: Similarly, findOperationHeaders is called to load WSDL-defined SOAP header declarations from the s2r_operation table. This allows the generator to document any required SOAP headers for each operation.

The generator service is responsible for merging the data from these separate calls to build the final OpenAPI specification.

flowchart TD
    subgraph OpenAPI Generation Service
        A[Start Generation for Service Version]
        J[Merge Configuration Data]
        K[Generate OpenAPI JSON]
    end

    subgraph OpenAPI Repository
        B[findServiceVersion]
        C[findEnabledOperations]
        D[findOperationFaults]
        E[findOperationHeaders]
        L[upsertArtifact]
    end

    subgraph Platform Database
        F[Service & Version Tables]
        G[Operation & Mapping Tables]
        H[WSDL Catalog Table]
        M[OpenAPI Artifact Table]
    end

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

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

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

    B --> J
    C --> J
    D --> J
    E --> J

    J --> K
    K --> L
    L --> M

Artifact Persistence

Once the OpenAPI JSON is generated, it is persisted using the upsertArtifact method. This method performs two main actions within a single database transaction:

1. It inserts or updates a record in the s2r_openapi_artifact table. It uses an INSERT ... ON CONFLICT statement, keyed on service_version_id, to ensure that each service version has at most one associated OpenAPI artifact.
2. It updates the corresponding record in the s2r_service_version table, setting the openapi_sha256 and openapi_generated_at columns to link the service version to the newly stored artifact.

This transactional approach guarantees that the artifact and the service version's link to it are always consistent.

API Reference

The OpenApiRepository class exposes the following public methods.

findServiceVersion

Retrieves a snapshot of metadata for a specific service version.

• Parameters:
  • serviceId (UUID): The ID of the service.
  • versionId (UUID): The ID of the service version.
• Returns: Optional<ServiceVersionSnapshot> containing the service version details, or Optional.empty() if not found.

findEnabledOperations

Retrieves a list of all enabled operations for a given service version, including all configuration overrides for the OpenAPI generator.

• Parameters:
  • versionId (UUID): The ID of the service version.
• Returns: List<OperationSnapshot> containing the detailed configuration for each enabled operation. Returns an empty list if no enabled operations are found.

findOperationFaults

Retrieves WSDL-defined wsdl:fault contracts for all operations in a service version. This data is used to generate specific error response schemas.

• Parameters:
  • versionId (UUID): The ID of the service version.
• Returns: Map<String, List<WsdlOperationFaultRecord>> where the key is the soap_operation_name and the value is a list of its declared fault records. Returns an empty map if no faults are defined or if the underlying database schema does not support this feature.

findOperationHeaders

Retrieves WSDL-defined soap:header declarations for all enabled operations in a service version.

• Parameters:
  • versionId (UUID): The ID of the service version.
• Returns: Map<String, List<WsdlOperationHeaderRecord>> where the key is the soap_operation_name and the value is a list of its declared header records. Returns an empty map if no headers are declared or if the underlying database schema does not support this feature.

upsertArtifact

Inserts a new OpenAPI artifact or updates an existing one for a given service version. This operation is transactional.

• Parameters:

  Name	Type	Required	Default	Description
  serviceId	UUID	Yes	—	The ID of the service.
  versionId	UUID	Yes	—	The ID of the service version.
  openapiJson	String	Yes	—	The full content of the generated OpenAPI specification in JSON format.
  sha256	String	Yes	—	The SHA-256 hash of the openapiJson content.
  actor	String	No	"system"	The identifier of the user or process that triggered the generation. If null or blank, defaults to "system".
  generatedAt	OffsetDateTime	Yes	—	The timestamp when the artifact was generated.

• Returns: OpenApiArtifactRecord representing the newly created or updated artifact record from the database.

listAllArtifactKeys

Lists the unique key pairs (serviceId, serviceVersionId) for all existing OpenAPI artifacts.

• Returns: List<ArtifactKey> containing all artifact keys, ordered by their generation timestamp in ascending order.

findArtifact

Retrieves a single, complete OpenAPI artifact record, including its JSON content.

• Parameters:
  • serviceId (UUID): The ID of the service.
  • versionId (UUID): The ID of the service version.
• Returns: Optional<OpenApiArtifactRecord> containing the full artifact record, or Optional.empty() if not found.

Data Model Reference

The repository methods return records that encapsulate data from the database.

ServiceVersionSnapshot

Basic metadata about a service version.

OpenApiArtifactRecord

Represents a stored OpenAPI artifact.

OperationSnapshot

A comprehensive record of an operation's configuration, used as input for the OpenAPI generator. A null value for any ...Override field typically means the operation inherits the system-level default setting.

Troubleshooting

The repository is designed to be resilient to missing data or older database schemas to prevent failures during OpenAPI generation.

• Missing Data in JSONB Columns: The helper methods (parseStringMap, parseObjectMap, etc.) that deserialize JSONB columns are robust. If a column contains null, a blank string, or malformed JSON, the method returns an empty Map or List. This prevents parsing errors and causes the generator to use the operation-level or system-level default for the affected fields.
• No Matching Records: The findServiceVersion and findArtifact methods return an Optional. If no record matches the provided serviceId and versionId, the Optional will be empty. Callers must check for this condition to avoid NoSuchElementException.
• Legacy Data Formats: The parseStringMap method can handle both legacy (plain string values) and modern (structured object values) formats within the same JSONB map. It extracts the relevant mode string from objects, ensuring backward compatibility.

See Also

• Data Models:
  • OpenApiArtifactRecord
  • WsdlOperationFaultRecord
  • WsdlOperationHeaderRecord
• Database Tables:
  • s2r_openapi_artifact
  • s2r_service_version
  • s2r_service
  • s2r_operation
  • s2r_operation_mapping
  • s2r_wsdl_operation_catalog

All SOAP-to-REST docs