|
| 1 | +## OpenAPIKit v4 Migration Guide |
| 2 | +For general information on the v4 release, see the release notes on GitHub. The |
| 3 | +rest of this guide will be formatted as a series of changes and what options you |
| 4 | +have to migrate code from v3 to v4. You can also refer back to the release notes |
| 5 | +for each of the v4 pre-releases for the most thorough look at what changed. |
| 6 | + |
| 7 | +This guide will not spend time on strictly additive features of version 4. See |
| 8 | +the release notes, README, and documentation for information on new features. |
| 9 | + |
| 10 | +### Swift version support |
| 11 | +OpenAPIKit v4.0 drops support for Swift versions prior to 5.8 (i.e. it supports |
| 12 | +v5.8 and greater). |
| 13 | + |
| 14 | +### Yams version support |
| 15 | +Yams is only a test dependency of OpenAPIKit, but since it is still a dependency |
| 16 | +it will still impact dependency resolution of downstream projects. Yams 5.1.0+ |
| 17 | +is now required. |
| 18 | + |
| 19 | +### MacOS version support |
| 20 | +Only relevant when compiling OpenAPIKit on macOS: Now v10_15+ is required. |
| 21 | + |
| 22 | +### OpenAPI Specification Versions |
| 23 | +The `OpenAPIKit.Document.Version` enum gained `v3_1_1` and the |
| 24 | +`OpenAPIKit30.Document.Version` enum gained `v3_0_4`. If you have exhaustive |
| 25 | +switches over values of those types then your switch statements will need to be |
| 26 | +updated. |
| 27 | + |
| 28 | +### Typo corrections |
| 29 | +The following typo corrections were made to OpenAPIKit code. These amount to |
| 30 | +breaking changes only in so far as you need to correct the same names if they |
| 31 | +appear in your codebase. |
| 32 | + |
| 33 | +- `public static Validation.serverVarialbeEnumIsValid` -> `.serverVariableEnumIsValid` |
| 34 | +- `spublic static Validation.erverVarialbeDefaultExistsInEnum` -> `.serverVariableDefaultExistsInEnum` |
| 35 | + |
| 36 | +### `AnyCodable` |
| 37 | +**NOTE** that the `AnyCodable` type is used extensively for OpenAPIKit examples |
| 38 | +and vendor extensions so that is likely where this note will be relevant to you. |
| 39 | + |
| 40 | +1. The constructor for `AnyCodable` now requires knowledge at compile time that |
| 41 | + the value it is initialized with is `Sendable`. |
| 42 | +2. Array and Dictionary literal protocol conformances had to be dropped. |
| 43 | + Anywhere you were relying on implicit conversion from e.g. `["hello": 1]` to |
| 44 | + an `AnyCodable`, wrap the literal with an explicit call to init: |
| 45 | + `.init(["hello": 1])`. |
| 46 | + |
| 47 | +### Vendor Extensions |
| 48 | +1. The `vendorExtensions` property of any `VendorExtendable` type must now |
| 49 | + implement a setter as well as a getter. This is not likely to impact |
| 50 | + downstream projects, but technically possible. |
| 51 | +2. If you are disabling `vendorExtensions` support via the |
| 52 | + `VendorExtensionsConfiguration.isEnabled` property, you need to switch to |
| 53 | + using encoder/decoder `userInfo` to disable vendor extensions. The |
| 54 | + `isEnabled` property has been removed. See the example below. |
| 55 | + |
| 56 | +To set an encoder or decoder up to disable vendor extensions use code like the |
| 57 | +following before using the encoder or decoder with an OpenAPIKit type: |
| 58 | +```swift |
| 59 | +let userInfo = [VendorExtensionsConfiguration.enabledKey: false] |
| 60 | +let encoder = JSONEncoder() |
| 61 | +encoder.userInfo = userInfo |
| 62 | + |
| 63 | +let decoder = JSONDecoder() |
| 64 | +decoder.userInfo = userInfo |
| 65 | +``` |
| 66 | + |
| 67 | +### `OpenAPI.Content.Encoding` |
| 68 | +The `contentType` property has been removed in favor of the newer `contentTypes` |
| 69 | +property (plural). |
| 70 | + |
| 71 | +### `JSONSchemaContext` |
| 72 | +The default (fallback) implementations of `inferred`, `anchor`, and |
| 73 | +`dynamicAnchor` have been removed. Almost no downstream code will break because |
| 74 | +of this, but if you've implemented the `JSONSchemaContext` protocol yourself |
| 75 | +then this note is for you. |
0 commit comments