Update to OpenAPIKit 3.0.0-alpha.9

[simonjbeaumont]

Motivation

Investigation into #128 led to a new release of OpenAPIKit, which supports path references. Supporting path references isn't something we want to do right now because:

1. OpenAPI 3.0.3 only supports external path references (cf. 3.1, which supports internal references too).
2. Swift OpenAPI Generator currently only supports OpenAPI 3.0.x.
3. Swift OpenAPI Generator currently doesn't support external references.

The OpenAPIKit update comes with a new API, because the paths are now an Either to support being a PathItem or a reference to a PathItem.

For now we'd like to be keeping up to date with OpenAPIKit so that, when we support OpenAPI 3.1 and/or external references, we have the APIs we need in the upstream package.

Modifications

• Update to OpenAPIKit 3.0.0-alpha.9.
• Attempt to resolve the path item during translation.

Result

An error will be thrown when using an OpenAPI document with a path reference.

Test Plan

Added reference tests.

[czechboy0]

lgtm!

[simonjbeaumont]

Interesting test failures:

Test Case 'Test_YamsParser.testEmitsComplexOpenAPIParsingError' started at 2023-08-01 10:26:00.831
/code/Tests/OpenAPIGeneratorCoreTests/Parser/Test_YamsParser.swift:123: error: Test_YamsParser.testEmitsComplexOpenAPIParsingError : XCTAssertEqual failed: ("/foo.yaml: error: Found neither a $ref nor a PathItem in Document.paths['/system']. 

PathItem could not be decoded because:
Expected to find `responses` key for the **GET** endpoint under `/system` but it is missing..") is not equal to ("/foo.yaml: error: Expected to find `responses` key for the **GET** endpoint under `/system` but it is missing.") -
Test Case 'Test_YamsParser.testEmitsComplexOpenAPIParsingError' failed (0.008 seconds)

This one is easy—just an error message changed in OpenAPIKit.

============================================================
Performing reference test
--- begin test config --------------------------------------
docFilePath: Docs/petstore.yaml
mode: types
additionalImports: []
featureFlags: []
referenceOutputDirectory: ReferenceSources/Petstore

--- end test config ----------------------------------------
/code/Tests/OpenAPIGeneratorReferenceTests/FileBasedReferenceTests.swift:108: error: FileBasedReferenceTests.testPetstore : failed - 
Directory contents not equal:
  File under test: Types.swift
  Reference file: ReferenceSources/Petstore/Types.swift
  Diff output: (see below)
--- begin diff output --------------------------------------
diff --git a/ReferenceSources/Petstore/Types.swift b/tmp/C40D09CF-8552-4A43-A718-A5E9EAD097F6/Types.swift
index 06c6d29..5f18bc9 100644
--- a/ReferenceSources/Petstore/Types.swift
+++ b/tmp/C40D09CF-8552-4A43-A718-A5E9EAD097F6/Types.swift
@@ -169,16 +169,16 @@ public enum Components {
             /// Extra information about the error.
             ///
             /// - Remark: Generated from `#/components/schemas/Error/extraInfo`.
             public struct extraInfoPayload: Codable, Equatable, Hashable, Sendable {
                 /// - Remark: Generated from `#/components/schemas/Error/extraInfo/value1`.
-                public var value1: Components.Schemas.ExtraInfo
+                public var value1: Components.Schemas.ExtraInfo?
                 /// Creates a new `extraInfoPayload`.
                 ///
                 /// - Parameters:
                 ///   - value1:
-                public init(value1: Components.Schemas.ExtraInfo) { self.value1 = value1 }
+                public init(value1: Components.Schemas.ExtraInfo? = nil) { self.value1 = value1 }
                 public init(from decoder: any Decoder) throws { value1 = try .init(from: decoder) }
                 public func encode(to encoder: any Encoder) throws {
                     try value1.encode(to: encoder)
                 }
             }

--- end diff output ----------------------------------------

This one is more interesting...

This is converting from this OpenAPI:

        extraInfo:
          description: Extra information about the error.
          allOf:
            - $ref: '#/components/schemas/ExtraInfo'

But an allOf must have "all of" the definitions present IIUC:

The OpenAPI Specification allows combining and extending model definitions using the allOf property of JSON Schema, in effect offering model composition. allOf takes an array of object definitions that are validated independently but together compose a single object.

This will need looking into further.

[simonjbeaumont]

This will need looking into further.

OK, so I've created some tests which isolate the issue. They pass without the OpenAPIKit upgrade, and fail with it. Doesn't necessarily mean it's a bug in OpenAPIKit—we could be making some incorrect assumptions.

I've rebased this branch with those commits, one at a time (tests first, then upgrade), to show the issue.

The above commit adds tests for the following:

---
# 1
            schemas:
              A:
                type: string
              MyAllOf:
                allOf:
                  - $ref: '#/components/schemas/A'
---
# 2
            schemas:
              A:
                type: string
              B:
                type: object
                required:
                  - c
                properties:
                  c:
                    allOf:
                      - $ref: "#/components/schemas/A"
---
# 3
            schemas:
              A:
                type: string
              B:
                type: object
                required: []
                properties:
                  c:
                    allOf:
                      - $ref: "#/components/schemas/A"

The difference between (2) and (3) should be in just the optionality of the c property within B. In both cases, cPayload.value1 should be non-optional.

The test is passing fine...

Now I'll push the update to upgrade OpenAPIKit.

[czechboy0]