Skip to content

Conversation

@mattpolzin
Copy link
Owner

@mattpolzin mattpolzin commented Nov 6, 2025

Closes #442

Breaking Changes / Migration Guide

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

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).

@mattpolzin mattpolzin force-pushed the feature/442/parameter-header-features branch from 7cdba6b to 574cf71 Compare November 6, 2025 15:53
@mattpolzin mattpolzin marked this pull request as ready for review November 9, 2025 22:56
@mattpolzin mattpolzin force-pushed the feature/442/parameter-header-features branch from 5d31384 to cb27c62 Compare November 9, 2025 22:57
@mattpolzin mattpolzin merged commit 00e4346 into release/5_0 Nov 10, 2025
15 checks passed
@mattpolzin mattpolzin deleted the feature/442/parameter-header-features branch November 10, 2025 10:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants