Ease Into Compatibility

This release simply exposes additional previously internal functions used to convert OpenAPI 3.0 compatible documents into OpenAPI 3.1 compatible documents.

These newly public functions are not intended to be used directly but using them directly can help downstream maintainers migrate code from the OpenAPIKit30 module to the OpenAPIKit module gradually instead of all at once so they are being exposed publicly for a limited time. They will be made private in a future release, likely either the final OpenAPIKit 3.0.0 release or perhaps not until the OpenAPIKit 4.0.0 releases. Regardless, they aren't to be relied upon for code that is intended to be permanent.

Last, But Not Least (3)

Some APIs differentiate between trailing slash or not for API paths which means that OpenAPIKit should as well. This fix makes the paths /hello/world and /hello/world/ distinct and, most importantly, if /hello/world/ is read in, then /hello/world/ is written out -- previously, OpenAPIKit would drop the trailing slash.

Last, But Not Least

Some APIs differentiate between trailing slash or not for API paths which means that OpenAPIKit should as well. This fix makes the paths /hello/world and /hello/world/ distinct and, most importantly, if /hello/world/ is read in, then /hello/world/ is written out -- previously, OpenAPIKit would drop the trailing slash.

Latest and Greatest

⚠️ This version attempts not to break anything, but it does move some types into different modules and use type aliasing to retain existing namespacing so there is some possibility of a problem there. Please report any issues you have if you move to this version in your project!

---

With this version, the new OpenAPIKitCompat module can be used to take an OpenAPIKit30.OpenAPI.Document and convert it into an OpenAPIKit.OpenAPI.Document. In other words, you can convert an OpenAPI v3.0 document into an OpenAPI v3.1 document. Equally as importantly, you can create projects with- (or migrate existing projects over to-) the OpenAPIKit module where they used to use the OpenAPIKit30 module and support the previous version of the OpenAPI standard by decoding to OpenAPIKit30.OpenAPI.Document and then calling convert(to: .v3_1_0) on the result.

For example, a (currently unreleased) branch of the OpenAPIDiff project supports both OpenAPI 3.0 and 3.1 in its main executable while most of the project only cares about OpenAPI 3.1 with the following code that decodes and converts v3.0 documents: https://github.com/mattpolzin/OpenAPIDiff/blob/openapikit-3/Sources/openapi-diff/main.swift#L63..L100

Here's the gist:

// import OpenAPIKit30 for OpenAPI 3.0 document support
import OpenAPIKit30
// import OpenAPIKit for OpenAPI 3.1 document support
import OpenAPIKit
// import OpenAPIKitCompat to convert between the versions
import OpenAPIKitCompat

// if most of your project just works with OpenAPI v3.1, most files only need to import OpenAPIKit.
// Only in the file where you are supporting converting from OpenAPI v3.0 to v3.1 do you need the
// other two imports.

// we can support either version by attempting to parse an old version and then a new version if the old version fails
let oldDoc: OpenAPIKit30.OpenAPI.Document?
let newDoc: OpenAPIKit.OpenAPI.Document

oldDoc = try? JSONDecoder().decode(OpenAPI.Document.self, from: someFileData)

newDoc = oldDoc?.convert(to: .v3_1_0) ??
  (try! JSONDecoder().decode(OpenAPI.Document.self, from: someFileData))

Relax (3)

Relax the version requirement for the Yams test dependency so that downstream projects can use more than 1 major version of Yams.

Relax

Relax the version requirement for the Yams test dependency so that downstream projects can use more than 1 major version of Yams.

`Link` And Subscribe

Well, mostly just Link.

This release introduces the Link type to support OpenAPI Link Objects where previously those objects were quietly ignored.

The release also fixes a bug where certain String values coming from YAML files could be accidentally parsed as non-string values (like the string 'inf' being parsed as infinity rather than simply the string "inf"). The bug is addressed by specifically looking for a string value (rather than letting AnyCodable decide) when we know the OpenAPI schema specifies a string type is expected. Thanks to @kean for finding and fixing the bug and then backporting it from the pre-release 3.0.0 branch to the main branch!

Just do your best

Among the other changes listed below, this release swaps out some errors that used to cause decoding to fail for warnings so that more documents can be decoded even if they don't quite follow the specification. The warnings are stored and you can get at them all easily by calling document.validate(strict: false) which returns all warnings that were produced. By default, validate() will be strict and all warnings will become validation failures, so validation still serves to determine whether a document really follows the spec. to the letter.

Big thanks to @kean for both the direct contributions to the code in this release and also the immensely helpful suggestions and bug reports.

Enhancements

• A few parsing errors have been turned into warnings when there is still some way to finish parsing a document despite a problem being found.
• OpenAPI 3.1 support (the OpenAPIKit module) for multiple examples on JSONSchema as specified by JSON Schema.
• You can disable VendorExtensions from being decoded or encoded (which can be a big boost to performance) by setting VendorExtensionsConfiguration.isEnabled = false. (@kean)
• OpenAPIKit retains the order of more decoded objects (including properties in JSONSchema objects). (@kean)

Bug Fixes

• Fix mistaken decoding of AnyCodable values that aren't strings when a JSONSchema's type is specified to be string. (@kean)

⚠️ Breaking Changes ⚠️

• The OpenAPIKit module (but not the OpenAPIKit30 module) now exposes only an examples property on JSONSchemas and their contexts. This is backwards compatible with example when decoding, but code that references example will need to be updated to use the new examples array instead.
• The externally available ContentType is changing from an enum to a struct. Equality checks for all of the previous enum's cases will still work against new static constructors but switch statements will no longer be possible.
• Code that works with the newly converted OrderedDictionary properties will likely work without modification, but there are some methods supported by Dictionary but not OrderedDictionary so some code may need to be tweaked. See #233 if you are curious what properties have changed.
• Response.StatusCode is changing from an enum to a struct. Code won't necessarily need to change, but switching on it will need to instead switch on its value property.
• JSONSchema is changing from an enum to a struct (as usual, to facilitate storage of warnings). For most code, use will not change, but if you switch over any JSONSchemas, you should change to switching over the newly exposed value property of JSONSchema instead.

A Linkable Moment

This release adds the missing Link Object to both the OpenAPI 3.1 and OpenAPI 3.0 modules.

Describe it to me differently

The biggest change since alpha 1 is that all occurrences of JSONReference outside of JSONSchema have been replaced by a new OpenAPI.Reference type.

This change only impacts the OpenAPIKit module that targets v3.1 of the specification. This alpha does not change the OpenAPIKit30 module that targets v3.0 of the spec.

This new type attempts to expose all of the same conveniences of JSONReference but it additionally introduces support for overriding the summary or description of the object being referenced. These overrides only apply when the referenced object would have already supported the summary or description field (otherwise the override is ignored). You can also find the JSONReference at the jsonReference property of an OpenAPI.Reference.

This move comes with a couple of small but definitely breaking changes to code that uses JSONReference directly. For example, anywhere you used to create a reference with JSONReference.internal(.path(...)) you will now use OpenAPI.Reference.internal(path: ...).