Merge pull request #387 from mattpolzin/oas-version-maintenance

OAS version maintenance

Author: mattpolzin

README.md

@@ -4,7 +4,7 @@
 
 # OpenAPIKit <!-- omit in toc -->
 
-A library containing Swift types that encode to- and decode from [OpenAPI 3.0.x](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md) and [OpenAPI 3.1.x](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md) Documents and their components.
+A library containing Swift types that encode to- and decode from [OpenAPI 3.0.x](https://spec.openapis.org/oas/v3.0.4.html) and [OpenAPI 3.1.x](https://spec.openapis.org/oas/v3.1.1.html) Documents and their components.
 
 OpenAPIKit follows semantic versioning despite the fact that the OpenAPI specificaiton does not. The following chart shows which OpenAPI specification versions and key features are supported by which OpenAPIKit versions.
 
@@ -149,7 +149,7 @@ let newDoc: OpenAPIKit.OpenAPI.Document
 
 oldDoc = try? JSONDecoder().decode(OpenAPI.Document.self, from: someFileData)
 
-newDoc = oldDoc?.convert(to: .v3_1_0) ??
+newDoc = oldDoc?.convert(to: .v3_1_1) ??
   (try! JSONDecoder().decode(OpenAPI.Document.self, from: someFileData))
 // ^ Here we simply fall-back to 3.1.x if loading as 3.0.x failed. You could do a more
 //   graceful job of this by determining up front which version to attempt to load or by 
@@ -165,7 +165,7 @@ If retaining order is important for your use-case, I recommend the [**Yams**](ht
 The Foundation JSON encoding and decoding will be the most stable and battle-tested option with Yams as a pretty well established and stable option as well. FineJSON is lesser used (to my knowledge) but I have had success with it in the past.
 
 ### OpenAPI Document structure
-The types used by this library largely mirror the object definitions found in the OpenAPI specification [version 3.1.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md) (`OpenAPIKit` module) and [version 3.0.3](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md) (`OpenAPIKit30` module). The [Project Status](#project-status) lists each object defined by the spec and the name of the respective type in this library. The project status page currently focuses on OpenAPI 3.1.x but for the purposes of determining what things are named and what is supported you can mostly infer the status of the OpenAPI 3.0.x support as well.
+The types used by this library largely mirror the object definitions found in the OpenAPI specification [version 3.1.1](https://spec.openapis.org/oas/v3.1.1.html) (`OpenAPIKit` module) and [version 3.0.4](https://spec.openapis.org/oas/v3.0.4.html) (`OpenAPIKit30` module). The [Project Status](#project-status) lists each object defined by the spec and the name of the respective type in this library. The project status page currently focuses on OpenAPI 3.1.x but for the purposes of determining what things are named and what is supported you can mostly infer the status of the OpenAPI 3.0.x support as well.
 
 #### Document Root
 At the root there is an `OpenAPI.Document`. In addition to some information that applies to the entire API, the document contains `OpenAPI.Components` (essentially a dictionary of reusable components that can be referenced with `JSONReferences` and `OpenAPI.References`) and an `OpenAPI.PathItem.Map` (a dictionary of routes your API defines).
@@ -289,7 +289,7 @@ let document = OpenAPI.Document(
 ```
 
 #### Specification Extensions
-Many OpenAPIKit types support [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#specification-extensions). As described in the OpenAPI Specification, these extensions must be objects that are keyed with the prefix "x-". For example, a property named "specialProperty" on the root OpenAPI Object (`OpenAPI.Document`) is invalid but the property "x-specialProperty" is a valid specification extension.
+Many OpenAPIKit types support [Specification Extensions](https://spec.openapis.org/oas/v3.1.1.html#specification-extensions). As described in the OpenAPI Specification, these extensions must be objects that are keyed with the prefix "x-". For example, a property named "specialProperty" on the root OpenAPI Object (`OpenAPI.Document`) is invalid but the property "x-specialProperty" is a valid specification extension.
 
 You can get or set specification extensions via the `vendorExtensions` property on any object that supports this feature. The keys are `Strings` beginning with the aforementioned "x-" prefix and the values are `AnyCodable`. If you set an extension without using the "x-" prefix, the prefix will be added upon encoding.
 

Sources/OpenAPIKit/Callbacks.swift

@@ -13,7 +13,7 @@ extension OpenAPI {
     /// A map from runtime expressions to path items to be used as
     /// callbacks for the API. The OpenAPI Spec "Callback Object."
     ///
-    /// See [OpenAPI Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#callback-object).
+    /// See [OpenAPI Callback Object](https://spec.openapis.org/oas/v3.1.1.html#callback-object).
     ///
     public typealias Callbacks = OrderedDictionary<CallbackURL, Either<OpenAPI.Reference<PathItem>, PathItem>>
 

Sources/OpenAPIKit/Components Object/Components.swift

@@ -11,7 +11,7 @@ import Foundation
 extension OpenAPI {
     /// OpenAPI Spec "Components Object".
     ///
-    /// See [OpenAPI Components Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#components-object).
+    /// See [OpenAPI Components Object](https://spec.openapis.org/oas/v3.1.1.html#components-object).
     /// 
     /// This is a place to put reusable components to
     /// be referenced from other parts of the spec.

Sources/OpenAPIKit/Content/Content.swift

@@ -10,7 +10,7 @@ import OpenAPIKitCore
 extension OpenAPI {
     /// OpenAPI Spec "Media Type Object"
     /// 
-    /// See [OpenAPI Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#media-type-object).
+    /// See [OpenAPI Media Type Object](https://spec.openapis.org/oas/v3.1.1.html#media-type-object).
     public struct Content: Equatable, CodableVendorExtendable {
         public var schema: Either<OpenAPI.Reference<JSONSchema>, JSONSchema>?
         public var example: AnyCodable?

Sources/OpenAPIKit/Content/ContentEncoding.swift

@@ -10,7 +10,7 @@ import OpenAPIKitCore
 extension OpenAPI.Content {
     /// OpenAPI Spec "Encoding Object"
     /// 
-    /// See [OpenAPI Encoding Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#encoding-object).
+    /// See [OpenAPI Encoding Object](https://spec.openapis.org/oas/v3.1.1.html#encoding-object).
     public struct Encoding: Equatable {
         public typealias Style = OpenAPI.Parameter.SchemaContext.Style
 

Sources/OpenAPIKit/Document/DereferencedDocument.swift

@@ -105,7 +105,7 @@ extension DereferencedDocument {
     /// each path, traversed in the order the paths appear in
     /// the document.
     ///
-    /// See [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#operation-object) in the specifcation.
+    /// See [Operation Object](https://spec.openapis.org/oas/v3.1.1.html#operation-object) in the specifcation.
     ///
     public var allOperationIds: [String] {
         return paths.values

Sources/OpenAPIKit/Document/Document.swift

@@ -10,7 +10,7 @@ import OpenAPIKitCore
 extension OpenAPI {
     /// The root of an OpenAPI 3.1 document.
     /// 
-    /// See [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md).
+    /// See [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.1.html).
     ///
     /// An OpenAPI Document can say a _lot_ about the API it describes.
     /// A read-through of the specification is highly recommended because
@@ -100,7 +100,7 @@ extension OpenAPI {
         ///
         /// Closely related to the callbacks feature, this section describes requests initiated other than by an API call, for example by an out of band registration.
         /// The key name is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the expected responses
-        /// See [OpenAPI Webhook Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#fixed-fields)
+        /// See [OpenAPI Webhook Object](https://spec.openapis.org/oas/v3.1.1.html#fixed-fields)
         public var webhooks: OrderedDictionary<String, Either<OpenAPI.Reference<OpenAPI.PathItem>, OpenAPI.PathItem>>
 
         /// A declaration of which security mechanisms can be used across the API.
@@ -142,7 +142,7 @@ extension OpenAPI {
         public var vendorExtensions: [String: AnyCodable]
 
         public init(
-            openAPIVersion: Version = .v3_1_0,
+            openAPIVersion: Version = .v3_1_1,
             info: Info,
             servers: [Server],
             paths: PathItem.Map,
@@ -229,7 +229,7 @@ extension OpenAPI.Document {
     /// each path, traversed in the order the paths appear in
     /// the document.
     ///
-    /// See [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#operation-object) in the specifcation.
+    /// See [Operation Object](https://spec.openapis.org/oas/v3.1.1.html#operation-object) in the specifcation.
     ///
     public var allOperationIds: [String] {
         return paths.values
@@ -413,7 +413,7 @@ extension OpenAPI {
     /// Multiple entries in this dictionary indicate all schemes named are
     /// required on the same request.
     ///
-    /// See [OpenAPI Security Requirement Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#security-requirement-object).
+    /// See [OpenAPI Security Requirement Object](https://spec.openapis.org/oas/v3.1.1.html#security-requirement-object).
     public typealias SecurityRequirement = [JSONReference<SecurityScheme>: [String]]
 }
 

Sources/OpenAPIKit/Document/DocumentInfo.swift

@@ -11,7 +11,7 @@ import Foundation
 extension OpenAPI.Document {
     /// OpenAPI Spec "Info Object"
     ///
-    /// See [OpenAPI Info Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#info-object).
+    /// See [OpenAPI Info Object](https://spec.openapis.org/oas/v3.1.1.html#info-object).
     public struct Info: Equatable, CodableVendorExtendable {
         public let title: String
         public let summary: String?
@@ -50,7 +50,7 @@ extension OpenAPI.Document {
 
         /// OpenAPI Spec "Contact Object"
         ///
-        /// See [OpenAPI Contact Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#contact-object).
+        /// See [OpenAPI Contact Object](https://spec.openapis.org/oas/v3.1.1.html#contact-object).
         public struct Contact: Equatable, CodableVendorExtendable {
             public let name: String?
             public let url: URL?
@@ -78,7 +78,7 @@ extension OpenAPI.Document {
 
         /// OpenAPI Spec "License Object"
         ///
-        /// See [OpenAPI License Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#license-object).
+        /// See [OpenAPI License Object](https://spec.openapis.org/oas/v3.1.1.html#license-object).
         public struct License: Equatable, CodableVendorExtendable {
             public let name: String
             public let identifier: Identifier?

Sources/OpenAPIKit/Example.swift

@@ -11,7 +11,7 @@ import Foundation
 extension OpenAPI {
     /// OpenAPI Spec "Example Object"
     ///
-    /// See [OpenAPI Example Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#example-object).
+    /// See [OpenAPI Example Object](https://spec.openapis.org/oas/v3.1.1.html#example-object).
     public struct Example: Equatable, CodableVendorExtendable {
         public let summary: String?
         public let description: String?

Sources/OpenAPIKit/ExternalDocumentation.swift

@@ -11,7 +11,7 @@ import Foundation
 extension OpenAPI {
     /// OpenAPI Spec "External Documentation Object"
     /// 
-    /// See [OpenAPI External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#external-documentation-object).
+    /// See [OpenAPI External Documentation Object](https://spec.openapis.org/oas/v3.1.1.html#external-documentation-object).
     public struct ExternalDocumentation: Equatable, CodableVendorExtendable {
         public var description: String?
         public var url: URL

Sources/OpenAPIKit/Header/Header.swift

@@ -10,7 +10,7 @@ import OpenAPIKitCore
 extension OpenAPI {
     /// OpenAPI Spec "Header Object"
     ///
-    /// See [OpenAPI Header Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#header-object).
+    /// See [OpenAPI Header Object](https://spec.openapis.org/oas/v3.1.1.html#header-object).
     public struct Header: Equatable, CodableVendorExtendable {
         public typealias SchemaContext = Parameter.SchemaContext
 

Sources/OpenAPIKit/Link.swift

@@ -15,7 +15,7 @@ import Foundation
 extension OpenAPI {
     /// OpenAPI Spec "Link Object"
     ///
-    /// See [OpenAPI Link Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#link-object).
+    /// See [OpenAPI Link Object](https://spec.openapis.org/oas/v3.1.1.html#link-object).
     public struct Link: Equatable, CodableVendorExtendable {
         /// The **OpenAPI**` `operationRef` or `operationId` field, depending on whether
         /// a `URL` of a remote or local Operation Object or a `operationId` (String) of an
@@ -24,7 +24,7 @@ extension OpenAPI {
         /// A map from parameter names to either runtime expressions that evaluate to values or
         /// constant values (`AnyCodable`).
         ///
-        /// See the docuemntation for the [OpenAPI Link Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#link-object) for more details.
+        /// See the docuemntation for the [OpenAPI Link Object](https://spec.openapis.org/oas/v3.1.1.html#link-object) for more details.
         ///
         /// Empty dictionaries will be omitted from encoding.
         public var parameters: OrderedDictionary<String, Either<RuntimeExpression, AnyCodable>>

Sources/OpenAPIKit/Operation/Operation.swift

@@ -10,7 +10,7 @@ import OpenAPIKitCore
 extension OpenAPI {
     /// OpenAPI Spec "Operation Object"
     /// 
-    /// See [OpenAPI Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#operation-object).
+    /// See [OpenAPI Operation Object](https://spec.openapis.org/oas/v3.1.1.html#operation-object).
     public struct Operation: Equatable, CodableVendorExtendable {
         public var tags: [String]?
         public var summary: String?

Sources/OpenAPIKit/Parameter/Parameter.swift

@@ -10,7 +10,7 @@ import OpenAPIKitCore
 extension OpenAPI {
     /// OpenAPI Spec "Parameter Object"
     /// 
-    /// See [OpenAPI Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#parameter-object).
+    /// See [OpenAPI Parameter Object](https://spec.openapis.org/oas/v3.1.1.html#parameter-object).
     public struct Parameter: Equatable, CodableVendorExtendable {
         public var name: String
 
@@ -162,7 +162,7 @@ extension OpenAPI.Parameter {
     /// containing exactly the things that differentiate
     /// one parameter from another, per the specification.
     ///
-    /// See [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#parameter-object).
+    /// See [Parameter Object](https://spec.openapis.org/oas/v3.1.1.html#parameter-object).
     internal struct ParameterIdentity: Hashable {
         let name: String
         let location: Context.Location

Sources/OpenAPIKit/Parameter/ParameterContext.swift

@@ -10,7 +10,7 @@ import OpenAPIKitCore
 extension OpenAPI.Parameter {
     /// OpenAPI Spec "Parameter Object" location-specific configuration.
     /// 
-    /// See [OpenAPI Parameter Locations](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#parameter-locations).
+    /// See [OpenAPI Parameter Locations](https://spec.openapis.org/oas/v3.1.1.html#parameter-locations).
     ///
     /// Query, Header, and Cookie parameters are
     /// all optional by default unless you pass

Sources/OpenAPIKit/Parameter/ParameterSchemaContext.swift

@@ -10,8 +10,8 @@ import OpenAPIKitCore
 extension OpenAPI.Parameter {
     /// OpenAPI Spec "Parameter Object" schema and style configuration.
     ///
-    /// See [OpenAPI Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#parameter-object)
-    /// and [OpenAPI Style Values](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#style-values).
+    /// See [OpenAPI Parameter Object](https://spec.openapis.org/oas/v3.1.1.html#parameter-object)
+    /// and [OpenAPI Style Values](https://spec.openapis.org/oas/v3.1.1.html#style-values).
     public struct SchemaContext: Equatable {
         public var style: Style
         public var explode: Bool
@@ -132,7 +132,7 @@ extension OpenAPI.Parameter.SchemaContext.Style {
     /// per the OpenAPI Specification.
     ///
     /// See the `style` fixed field under
-    /// [OpenAPI Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#parameter-object).
+    /// [OpenAPI Parameter Object](https://spec.openapis.org/oas/v3.1.1.html#parameter-object).
     public static func `default`(for location: OpenAPI.Parameter.Context) -> Self {
         switch location {
         case .query:

Sources/OpenAPIKit/Path Item/PathItem.swift

@@ -10,7 +10,7 @@ import OpenAPIKitCore
 extension OpenAPI {
     /// OpenAPI Spec "Path Item Object"
     /// 
-    /// See [OpenAPI Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#path-item-object).
+    /// See [OpenAPI Path Item Object](https://spec.openapis.org/oas/v3.1.1.html#path-item-object).
     ///
     /// In addition to parameters that apply to all endpoints under the current path,
     /// this type offers access to each possible endpoint operation under properties

Sources/OpenAPIKit/Request/Request.swift

@@ -10,7 +10,7 @@ import OpenAPIKitCore
 extension OpenAPI {
     /// OpenAPI Spec "Request Body Object"
     ///
-    /// See [OpenAPI Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#request-body-object).
+    /// See [OpenAPI Request Body Object](https://spec.openapis.org/oas/v3.1.1.html#request-body-object).
     public struct Request: Equatable, CodableVendorExtendable {
         public var description: String?
         public var content: Content.Map

Sources/OpenAPIKit/Response/Response.swift

@@ -10,7 +10,7 @@ import OpenAPIKitCore
 extension OpenAPI {
     /// OpenAPI Spec "Response Object"
     ///
-    /// See [OpenAPI Response Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object).
+    /// See [OpenAPI Response Object](https://spec.openapis.org/oas/v3.1.1.html#response-object).
     public struct Response: Equatable, CodableVendorExtendable {
         public var description: String
         public var headers: Header.Map?

Sources/OpenAPIKit/RuntimeExpression.swift

@@ -10,7 +10,7 @@ import OpenAPIKitCore
 extension OpenAPI {
     /// OpenAPI Spec "Runtime Expression"
     ///
-    /// See [OpenAPI Runtime Expression[(https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#runtime-expressions).
+    /// See [OpenAPI Runtime Expression[(https://spec.openapis.org/oas/v3.1.1.html#runtime-expressions).
     ///
     public enum RuntimeExpression: RawRepresentable, Equatable {
         case url

Sources/OpenAPIKit/Schema Object/JSONSchema.swift

@@ -9,7 +9,7 @@ import OpenAPIKitCore
 
 /// OpenAPI "Schema Object"
 /// 
-/// See [OpenAPI Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#schema-object).
+/// See [OpenAPI Schema Object](https://spec.openapis.org/oas/v3.1.1.html#schema-object).
 public struct JSONSchema: JSONSchemaContext, HasWarnings {
 
     public let warnings: [OpenAPI.Warning]