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

Officially Clarified

What's Changed

• Support OAS 3.1.2 by @mattpolzin in #426

Full Changelog: 4.1.0...4.2.0