A Key Detail

What's Changed

I've only fixed this bug (which comes up in very few situations) for the OpenAPIKit module. It could be ported to the OpenAPIKit30 module very easily if desired in the future.

• Support key validation for OrderedDictionary maps (#486)

Full Changelog: 5.2.0...5.2.1

Strictly Speaking

What's Changed

You can now replace the default reference validations (that references pointing at the Components Object can be found in the Components Object) with a stricter set of reference validations (that references all point at the Components Object (i.e. are not external or internal but not Components) and they can be found in the Components Object). You do this by calling validatingAllReferencesFoundInComponents() on a Validator. You can also skip references validations (including those on by default) by calling skippingReferenceValidations() on a Validator. These two can be used to run validations twice if desired, once with the strict flag set to true (generate errors) and a second time with strict set to false (generate warnings) and only running reference validations for one of those two passes if you want to be stricter about references than you are about other validations.

• support stricter reference validations (#485)

Full Changelog: 5.1.1...5.2.0

Look me up

What's Changed

• Add missing lookupOnce variants (#483)

Full Changelog: 5.1.0...5.1.1

In Reference to Your Referral

What's Changed

• switch to foundation-essentials imports (as much as possible for now) by @mattpolzin in #480
• Add some conveniences for working with references to JSON Schemas by @mattpolzin in #482

Full Changelog: 5.0.0...5.1.0

Small changes, big footprint

See the migration guide before updating to OpenAPIKit v5.0.0. There were a fair number of breaking changes (each one fairly small on its own) required to support the new standard version.

What's Changed

See the migration guide and individual Release Notes for the pre-releases of version 5 to get a full picture but here are some highlights:

• Support for OpenAPI Standard 3.2.0 features.
• The default version for new documents is 3.2.0 now.
• Component Object entries can now be references.
• Swift version 5.10+ is now required.
• The official YAML media type is now preferred over application/x-yaml, though the old media type is still supported.
• JSON Schema values now (finally) support the xml property.

New Contributors

• @Kyome22 made their first contribution in #455

Full Changelog: 4.3.1...5.0.0

I have a name, you know

NOTE: These release notes only describe the changes since the previous release candidate. See the migration guide as well if you are migrating from a 4.x release.

What's Changed

• OAS 3.2.0 Server Object changes (#473)

Full Changelog: 5.0.0-rc.1...5.0.0-rc.2

XMLove

What's Changed

• Make OAS 3.2.0 changes to the OpenAPI.XML type (#472)

Full Changelog: 5.0.0-beta.3...5.0.0-rc.1

Setting A Good Example

What's Changed

• OAS 3.2.0 Example field support (#466)

Breaking Changes

Example Object (OpenAPI.Example)

There are no breaking changes to the OpenAPIKit30 module in this section.

OAS 3.2.0 introduced new fields along with restrictions around what combinations
of those fields can be used together. This warranted a restructuring of the
OpenAPIKit types to represent all new and existing restrictions together.

The old OpenAPI.Example value property was an Either to represent either an
inline value or an external value. The new value property is of the
OpenAPI.Example.Value type.

If you accessed the codableValue of the OpenAPI.Example value property
before, now you access the legacyValue or dataOrLegacyValue of the OpenAPI.Example:

// BEFORE
let codableValue = example.value?.codableValue

// AFTER
let codableValue = example.legacyValue

// AFTER (a bit more future-proof)
let codableValue = example.dataOrLegacyValue

// AFTER (if you've migrated to only using `dataValue`)
let codableValue = example.dataValue

If you accessed the urlValue of the OpenAPI.Example value property
before, now you access the externalValue of the openAPI.Example:

// BEFORE
let urlValue = example.value?.urlValue

// AFTER
let urlValue = example.externalValue

Initializers

The Example.init(summary:description:value:vendorExtensions:) initializer has
been deprecated. Your code should either use the new
Example.init(summary:description:legacyValue:vendorExtensions:) initializer
(direct replacement) or switch to one of two new initializers that adopts the
OAS 3.2.0 recommendations for semantics dependening on whether the example value
in question represents the structure of the example, the serialized form of
the example, or an external reference to the example:

// BEFORE (structural example)
let example = OpenAPI.Example(value: .b(.init(["hi": "hello"])))

// AFTER (structural example)
let example = OpenAPI.Example(dataValue: .init(["hi": "hello"]))

// BEFORE (serialized example, xml)
let example = OpenAPI.Example(value: .b("<hi>hello</hi>"))

// AFTER (serialized example, xml)
let example = OpenAPI.Example(serialzedValue: "<hi>hello</hi>")

// BEFORE (external value)
let example = OpenAPI.Example(
  value: .a(URL(string: "https://example.com/example.json")!)
)

// AFTER (external value)
let example = OpenAPI.Example(
  externalValue: URL(string: "https://example.com/example.json")!
)

Full Changelog: 5.0.0-beta.2...5.0.0-beta.3

~Reducible~ Reusable ~Recyclable~ Content

What's Changed

• Bump the default Document OAS version to 3.2.0 (#459)
• Fix external loader sendable warning/error (#461)
• Add OAS 3.2.0 defaultMapping field for Discriminator Object (#464)
• Add OAS 3.2.0 mediaTypes to Components Object (#465)
• Support OpenAPI.Content references in OpenAPI.Content.Map entries (#465)

Breaking Changes

The ExternalLoader protocol now requires SendableMetatype conformance. This should be a given in most cases.

The default OAS version of a Document has been updated to v3_2_0. If you
need to produce a v3_1_x document, update your code to specify that version in
the OpenAPI.Document constructor.

Content Map (OpenAPI.Content.Map)

Content maps now reflect the specification correctly in allowing references to
Media Type Objects (OpenAPI.Content). This means that code that creates or
reads OpenAPI.Content values from a Content.Map needs to be updated to dig
one level deeper and account for the possibility that the Content is
referenced to instead of inlined.

// BEFORE
let contentMap: OpenAPI.Content.Map = [
  .json: .init(schema: .string)
]
let jsonContent: OpenAPI.Content? = contentMap[.json]

// AFTER
let contentMap: OpenAPI.Content.Map = [
  .json: .content(.init(schema: .string)),
  .xml: .component(named: "xml")
]
let jsonContent: OpenAPI.Content? = contentMap[.json]?.contentValue
if case let .b(jsonContent) = contentMap[.json] { /*...*/ }

let referenceToContent: OpenAPI.Reference<OpenAPI.Content>? = contentMap[.xml]?.reference
if case let .a(referenceToContent) = contentMap[.xml] { /*...*/ }

If you are constructing an OpenAPI.Content.Map, you have one other option for
migrating existing code: You can use the new .direct() convenience
constructor:

// BEFORE
let contentMap: OpenAPI.Content.Map = [
  .json: .init(schema: .string)
]

// AFTER
let contentMap: OpenAPI.Content.Map = [
  .json: .content(.init(schema: .string))
]
// OR
let contentMap: OpenAPI.Content.Map = .direct([
  .json: .init(schema: .string)
])

Full Changelog: 5.0.0-beta.1...5.0.0-beta.2

Security for the win

What's Changed

• OAS 3.2.0 security scheme features (#457)

Breaking Changes

Security Scheme Object (OpenAPI.SecurityScheme)

The type property's enumeration gains a new associated value on the oauth2
case.

Existing code that switches on that property will need to be updated to match on
oauth2(flows: OAuthFlows, metadataUrl: URL?) now.

Full Changelog: 5.0.0-alpha.7...5.0.0-beta.1