Just stream me the thing

What's Changed

• Clearly indicate that this library is the MIT License. by @Kyome22 in #455
• OAS 3.2.0 multipart media support by @mattpolzin in #456

Breaking Changes

Media Type Object (OpenAPI.Content)

Schema property

The schema property has changed from either an OpenAPI.Reference or a
JOSNSchema to just a JSONSchema. This both reflects the specification and
also works just as well because JSONSchema has its own .reference case.
However, this does result in some necessary code changes.

You now have one fewer layer to traverse to get to a schema.

/// BEFORE
let JSONSchema? = content[.json]?.schema?.schemaValue

/// AFTER
let JSONSchema? = content[.json]?.schema

Switches over the schema now should look directly at the JSONSchema value
to switch on whether the schema is a reference or not.

/// BEFORE
guard let schema = content[.json]?.schema else { return }
switch schema {
case .a(let reference):
  print(reference)
case .b(let schema):
  print(schema)
}

/// AFTER
guard let schema = content[.json]?.schema else { return }
switch schema.value {
case .reference(let reference, _):
  print(reference)
default:
  print(schema)
}

The OpenAPI.Content(schema:example:encoding:vendorExtensions:) initializer
takes a schema directly so if you were passing in a schema anyway you just
remove one layer of wrapping (the Either that was previously there). If you
were passing in a reference, just make sure you are using the JSONSchema
reference() convenience constructor where it would have previously been the
Either reference() convenience constructor; they should be source-code
compatible.

Encoding property

The OpenAPI.Content encoding property has changed from being a map of
encodings (OrderedDictionary<String, Encoding>) to an Either in order to
support the new OAS 3.2.0 prefixEncoding and itemEncoding options which are
mutually exclusive with the existing map of encodings.

Anywhere you read the encoding property in your existing code, you can switch
to the encodingMap property if you want a short term solution that compiles
and behaves the same way for any OpenAPI Documents that do not use the new
positional encoding properties.

/// BEFORE
let encoding: Encoding? = content.encoding

/// AFTER
let encoding: Encoding? = content.encodingMap

If you wish to handle the new encoding options, you will need to switch over the
Either or otherwise handle the additional prefixEncoding and itemEncoding
properties.

guard let encoding = content.encoding else { return }
switch encoding {
case .a(let encodingMap):
  print(encodingMap)
case .b(let positionalEncoding):
  print(positionalEncoding.prefixEncoding)
  print(positionalEncoding.itemEncoding)
}

New Contributors

• @Kyome22 made their first contribution in #455

Full Changelog: 5.0.0-alpha.6...5.0.0-alpha.7

Your references have references

What's Changed

• Support references in Components Object entries (#454)

High Level

The Components Object now supports references in its entries everywhere the OpenAPI Specification allows it.

Breaking Changes

Components Object

There are changes for the OpenAPIKit30 module (OAS 3.0.x specification) in
this section.

Entries in the Components Object's responses, parameters, examples,
requestBodies, headers, securitySchemes, links, and callbacks
dictionaries have all gained support for references. Note that pathItems and
schemas still do not support references (per the specification), though
schemas can be JSON references by their very nature already.

This change fixes a gap in OpenAPIKit's ability to represent valid documents.

If you are using subscript access or lookup() functions to retrieve entries
from the Components Object, you do not need to change that code. These
functions have learned how to follow references they encounter until they land
on the type of entity being looked up. If you want the behavior of just
doing a regular lookup and passing the result back even if it is a reference,
you can use the new lookupOnce() function. The existing lookup() functions
can now throw an error they would never throw before: ReferenceCycleError.

Error message phrasing has changed subtly which is unlikely to cause problems
but if you have tests that compare exact error messages then you may need to
update the test expectations.

If you construct Components in-code then you have two options. You can swap
out existing calls to the Components init() initializer with calls to the
new Components.direct() convenience constructor or you can nest each component
entry in an Either like follows:

// BEFORE
Components(
  parameters: [
    "param1": .cookie(name: "cookie", schema: .string)
  ]
)

// AFTER
Components(
  parameters: [
    "param1": .parameter(.cookie(name: "cookie", schema: .string))
  ]
)

If your code uses the static openAPIComponentsKeyPath variable on types that
can be found in the Components Object (likely very uncommon), you will now need
to handle two possibilities: the key path either refers to an object (of generic
type T) or it refers to an Either<OpenAPI.Reference<T>, T>.

Full Changelog: 5.0.0-alpha.5...5.0.0-alpha.6

OAS 3.2.0 Improvements

What's Changed

• Add Document's $self property (#440)
• Add OAS 3.2.0 parameter header features (#451)
• Add OAS 3.2.0 cookie style (#452)
• Implement OAS 3.2.0 Response Object tweaks (#453)

Breaking Changes

Parameters

There are no breaking changes for the OpenAPIKit30 module (OAS 3.0.x
specification) in this section.

For the OpenAPIKit module (OAS 3.1.x and 3.2.x versions) read on.

An additional parameter location of querystring has been added. This is a
breaking change to code that exhaustively switches on OpenAPI.Parameter.Context
or OpenAPI.Parameter.Context.Location.

To support the new querystring location, schemaOrContent has been moved into
the OpenAPI.Parameter.Context because it only applies to locations other than
querystring. You can still access schemaOrContent as a property on the
Parameter. Code that pattern matches on cases of OpenAPI.Parameter.Context
will need to add the new schemaOrContent values associated with each case.

// BEFORE
switch parameter.context {
case .query(required: _)
}

// AFTER
switch parameter.context {
case .query(required: _, schemaOrContent: _)
}

Constructors

The following only applies if you construct parameters in-code (use Swift to
build an OpenAPI Document).

Unfortunately, the change that made schemaOrContent not apply to all possible
locations means that the existing convenience constructors and static functions
that created parameters in-code do not make sense anymore. There were fairly
substantial changes to what is available with an aim to continue to offer
simular convenience as before.

Following are a few changes you made need to make with examples.

Code that populates the parameters array of the OpenAPI.Operation type with the
.parameter(name:,context:,schema:) function needs to be updated. The schema
has moved into the context so you change your code in the following way:

// BEFORE
.parameter(
  name: "name",
  context: .header,
  schema: .string
)

// AFTER
.parameter(
  name: "name",
  context: .header(schema: .string)
)

Code that initializes OpenAPI.Parameter via one of its init functions will
most likely need to change. Many of the initializers have been removed but you can
replace .init(name:,context:,schema:) or similar initializers with
.header(name:,schema:) (same goes for query, path, and cookie). So you change
your code in the following way:

// BEFORE
.init(
  name: "name",
  context: .header,
  schema: .string
)

// AFTER
.header(
  name: "name",
  schema: .string
)

Because the ParameterContext has taken on the schemaOrContent of the
Parameter, convenience constructors like ParameterContext.header (and
similar for the other locations) no longer make sense and have been removed. You
must also specify the schema or content, e.g. ParameterContext.header(schema: .string).

Parameter Styles

There are no breaking changes for the OpenAPIKit30 module (OAS 3.0.x
specification) in this section.

A new cookie style has been added. Code that exhaustively switches on the
OpenAPI.Parameter.SchemaContext.Style enum will need to be updated.

Response Objects

There are no breaking changes for the OpenAPIKit30 module (OAS 3.0.x
specification) in this section.

The Response Object description field is not optional so code may need to
change to account for it possibly being nil.

Full Changelog: 5.0.0-alpha.4...5.0.0-alpha.5

More Consistency

What's Changed

• Add missing OAS version property (#437)

In short, whereas OAS version 3.1.2 was added in a non-breaking way via the Version.v3_1_x(x: 2) enum case, this patch adds the missing static property that allows you to refer to that new version as simply Version.v3_1_2 which is in line with prior versions like v3_1_1.

Full Changelog: 4.3.0...4.3.1

Additional Paths To Success

What's Changed

• Add new OAS 3.2.0 HTTP method support (#432)

Breaking Changes

• The OpenAPIKit30 module's OpenAPI.HttpMethod type has been renamed to OpenAPI.BuiltinHttpMethod and gained the .query method (though this method cannot be represented on the OAS 3.0.x Path Item Object).
• The OpenAPI module's OpenAPI.HttpMethod type has been updated to support non-builtin HTTP methods with the pre-existing HTTP methods moving to the OpenAPI.BuiltinHttpMethod type and HttpMethod having just two cases: .builtin(BuiltinHttpMethod) and .other(String).

Full Changelog: 5.0.0-alpha.3...5.0.0-alpha.4

Forwards Is Backwards (5)

What's Changed

• Add support for mapping newer OAS versions to older ones (#433)

Warning

Although this change is not being considered breaking, it does subtly change the phrasing of decoding errors for the Document Version. This may cause some tests written to expect exact string values for errors to fail.

Details

OpenAPIKit adds support for new OAS versions when it has support for most or
all of the features of that OAS version. If you want to parse an OpenAPI
Document that is written in a newer version than OpenAPIKit supports and you
are asserting that the newer version is possible to parse as if it were the
pre-existing version, you can tell OpenAPIKit to parse the newer version as if
it were the older version.

You do this with userInfo passed into the Decoder you are using. For
example, to decode a hypothetical document version of "3.100.100" as if it
were version "3.1.1", set your decoder up as follows:

let userInfo = [
  DocumentConfiguration.versionMapKey: ["3.100.100": OpenAPI.Document.Version.v3_1_1]
]

let decoder = ... // JSONDecoder() or YAMLDecoder()
decoder.userInfo = userInfo

let openAPIDoc = try decoder.decode(OpenAPI.Document.self, from: ...)

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

Forwards Is Backwards

What's Changed

• Add support for mapping newer OAS versions to older ones (#433)

Warning

Although this change is not being considered breaking, it does subtly change the phrasing of decoding errors for the Document Version. This may cause some tests written to expect exact string values for errors to fail.

Details

OpenAPIKit adds support for new OAS versions when it has support for most or
all of the features of that OAS version. If you want to parse an OpenAPI
Document that is written in a newer version than OpenAPIKit supports and you
are asserting that the newer version is possible to parse as if it were the
pre-existing version, you can tell OpenAPIKit to parse the newer version as if
it were the older version.

You do this with userInfo passed into the Decoder you are using. For
example, to decode a hypothetical document version of "3.100.100" as if it
were version "3.1.1", set your decoder up as follows:

let userInfo = [
  DocumentConfiguration.versionMapKey: ["3.100.100": OpenAPI.Document.Version.v3_1_1]
]

let decoder = ... // JSONDecoder() or YAMLDecoder()
decoder.userInfo = userInfo

let openAPIDoc = try decoder.decode(OpenAPI.Document.self, from: ...)

Full Changelog: 4.2.0...4.3.0

Forwards Is Backwards (Backport)

What's Changed

• Backport of #433 (Add support for mapping newer OAS versions to older ones) in #434

Warning

Although this change is not being considered breaking, it does subtly change the phrasing of decoding errors for the Document Version. This may cause some tests written to expect exact string values for errors to fail.

Details

OpenAPIKit adds support for new OAS versions when it has support for most or
all of the features of that OAS version. If you want to parse an OpenAPI
Document that is written in a newer version than OpenAPIKit supports and you
are asserting that the newer version is possible to parse as if it were the
pre-existing version, you can tell OpenAPIKit to parse the newer version as if
it were the older version.

You do this with userInfo passed into the Decoder you are using. For
example, to decode a hypothetical document version of "3.100.100" as if it
were version "3.1.1", set your decoder up as follows:

let userInfo = [
  DocumentConfiguration.versionMapKey: ["3.100.100": OpenAPI.Document.Version.v3_1_1]
]

let decoder = ... // JSONDecoder() or YAMLDecoder()
decoder.userInfo = userInfo

let openAPIDoc = try decoder.decode(OpenAPI.Document.self, from: ...)

Full Changelog: 3.8.0...3.9.0

Bit By Bit

Note that OAS 3.2.0 features are not fully supported even though the "3.2.0" version string is accepted as valid as of this release. New OAS 3.2.0 features will be added over the coming pre-releases.

What's Changed

• Add OAS v3.2.0 representation. Add OAS 3.2.0 improvements to the Tag object (#429)
• Support and prefer new official yaml media type (#430)

Breaking

• Document Version enum gains entries for OAS 3.2.x.
• application/x-yaml remains supports on decode but will always be encoded as application/yaml going forward.

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

5.0.0-alpha.1

Move support for OAS v3.1.2 into the Versions enum.

Breaking Changes

Support for OAS 3.1.2 has been moved into the Versions enum making it a bit more ergonomic to refer to but also breaking any switch statements that enumerate the versions.

Full Changelog: 4.2.0...5.0.0-alpha.1