diff --git a/README.md b/README.md index 181a9c98f..bd30e7801 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -[![sswg:sandbox|94x20](https://img.shields.io/badge/sswg-sandbox-lightgrey.svg)](https://github.com/swift-server/sswg/blob/master/process/incubation.md#sandbox-level) [![Swift 5.1+](http://img.shields.io/badge/Swift-5.1+-blue.svg)](https://swift.org) +[![sswg:sandbox|94x20](https://img.shields.io/badge/sswg-sandbox-lightgrey.svg)](https://github.com/swift-server/sswg/blob/master/process/incubation.md#sandbox-level) [![Swift 5.8+](http://img.shields.io/badge/Swift-5.8+-blue.svg)](https://swift.org) [![MIT license](http://img.shields.io/badge/license-MIT-lightgrey.svg)](http://opensource.org/licenses/MIT) ![Tests](https://github.com/mattpolzin/OpenAPIKit/workflows/Tests/badge.svg) @@ -10,8 +10,8 @@ OpenAPIKit follows semantic versioning despite the fact that the OpenAPI specifi | OpenAPIKit | Swift | OpenAPI v3.0 | OpenAPI v3.1 | External Dereferencing | |------------|-------|--------------|--------------|------------------------| -| v2.x | 5.1+ | ✅ | ❌ | ❌ | -| v3.x | 5.1+ | ✅ | ✅ | ❌ | +| v2.x | 5.1+ | ✅ | | | +| v3.x | 5.1+ | ✅ | ✅ | | | v4.x | 5.8+ | ✅ | ✅ | ✅ | - [Usage](#usage) @@ -76,7 +76,7 @@ import OpenAPIKit It is recommended that you build your project against the `OpenAPIKit` module and only use `OpenAPIKit30` to support reading OpenAPI 3.0.x documents in and then [converting them](#supporting-openapi-30x-documents) to OpenAPI 3.1.x documents. The situation not supported yet by this strategy is where you need to write out an OpenAPI 3.0.x document (as opposed to 3.1.x). That is a planned feature but it has not yet been implemented. If your use-case benefits from reading in an OpenAPI 3.0.x document and also writing out an OpenAPI 3.0.x document then you can operate entirely against the `OpenAPIKit30` module. #### 3.x to 4.x -This section has not been written yet. Stay tuned! +If you are migrating from OpenAPIKit 3.x to OpenAPIKit 4.x, check out the [v4 migration guide](./documentation/v4_migration_guide.md). ### Decoding OpenAPI Documents diff --git a/documentation/v4_migration_guide.md b/documentation/v4_migration_guide.md new file mode 100644 index 000000000..0632ecb5f --- /dev/null +++ b/documentation/v4_migration_guide.md @@ -0,0 +1,75 @@ +## OpenAPIKit v4 Migration Guide +For general information on the v4 release, see the release notes on GitHub. The +rest of this guide will be formatted as a series of changes and what options you +have to migrate code from v3 to v4. You can also refer back to the release notes +for each of the v4 pre-releases for the most thorough look at what changed. + +This guide will not spend time on strictly additive features of version 4. See +the release notes, README, and documentation for information on new features. + +### Swift version support +OpenAPIKit v4.0 drops support for Swift versions prior to 5.8 (i.e. it supports +v5.8 and greater). + +### Yams version support +Yams is only a test dependency of OpenAPIKit, but since it is still a dependency +it will still impact dependency resolution of downstream projects. Yams 5.1.0+ +is now required. + +### MacOS version support +Only relevant when compiling OpenAPIKit on macOS: Now v10_15+ is required. + +### OpenAPI Specification Versions +The `OpenAPIKit.Document.Version` enum gained `v3_1_1` and the +`OpenAPIKit30.Document.Version` enum gained `v3_0_4`. If you have exhaustive +switches over values of those types then your switch statements will need to be +updated. + +### Typo corrections +The following typo corrections were made to OpenAPIKit code. These amount to +breaking changes only in so far as you need to correct the same names if they +appear in your codebase. + +- `public static Validation.serverVarialbeEnumIsValid` -> `.serverVariableEnumIsValid` +- `spublic static Validation.erverVarialbeDefaultExistsInEnum` -> `.serverVariableDefaultExistsInEnum` + +### `AnyCodable` +**NOTE** that the `AnyCodable` type is used extensively for OpenAPIKit examples +and vendor extensions so that is likely where this note will be relevant to you. + +1. The constructor for `AnyCodable` now requires knowledge at compile time that + the value it is initialized with is `Sendable`. +2. Array and Dictionary literal protocol conformances had to be dropped. + Anywhere you were relying on implicit conversion from e.g. `["hello": 1]` to + an `AnyCodable`, wrap the literal with an explicit call to init: + `.init(["hello": 1])`. + +### Vendor Extensions +1. The `vendorExtensions` property of any `VendorExtendable` type must now + implement a setter as well as a getter. This is not likely to impact + downstream projects, but technically possible. +2. If you are disabling `vendorExtensions` support via the + `VendorExtensionsConfiguration.isEnabled` property, you need to switch to + using encoder/decoder `userInfo` to disable vendor extensions. The + `isEnabled` property has been removed. See the example below. + +To set an encoder or decoder up to disable vendor extensions use code like the +following before using the encoder or decoder with an OpenAPIKit type: +```swift +let userInfo = [VendorExtensionsConfiguration.enabledKey: false] +let encoder = JSONEncoder() +encoder.userInfo = userInfo + +let decoder = JSONDecoder() +decoder.userInfo = userInfo +``` + +### `OpenAPI.Content.Encoding` +The `contentType` property has been removed in favor of the newer `contentTypes` +property (plural). + +### `JSONSchemaContext` +The default (fallback) implementations of `inferred`, `anchor`, and +`dynamicAnchor` have been removed. Almost no downstream code will break because +of this, but if you've implemented the `JSONSchemaContext` protocol yourself +then this note is for you.