Merge pull request #122 from mattpolzin/ordered-dict-subscript-ambiguity

Address ambiguity with StatusCode-keyed OrderedDictionary.

Author: mattpolzin

Sources/OpenAPIKit/Operation/Operation.swift

@@ -17,6 +17,46 @@ extension OpenAPI {
         public var operationId: String?
         public var parameters: Parameter.Array
         public var requestBody: Either<JSONReference<OpenAPI.Request>, OpenAPI.Request>?
+        /// The possible responses for this operation, keyed by status code.
+        ///
+        /// The status code keys can be integer values, ranges, or even the
+        /// `default` which just refers to the response to expect where no
+        /// other respones apply.
+        ///
+        /// Because the map is ordered, you can access responses by either
+        /// status code or index. Notice that the values of this dictionary are actually
+        /// `Either` an inline `Response` or a reference to a `Response` that is
+        /// defined elsewhere.
+        ///
+        /// **Example:**
+        ///
+        ///     let firstResponse: (OpenAPI.Response.StatusCode, Either<JSONReference<OpenAPI.Response>, OpenAPI.Response>)
+        ///     firstResponse = operation.responses[0]!
+        ///
+        ///     // literally documented as "200" status code:
+        ///     let successResponse: Either<JSONReference<OpenAPI.Response>, OpenAPI.Response>
+        ///     successResponse = operation.responses[status: 200]!
+        ///
+        ///     // documented as "2XX" status code:
+        ///     let successResponse2: Either<JSONReference<OpenAPI.Response>, OpenAPI.Response>
+        ///     successResponse2 = operation.responses[.range(.success)]!
+        ///
+        /// If you want to access the response (assuming it is inlined) you need to grab
+        /// it out of the `Either`.
+        ///
+        /// **Example:**
+        ///
+        ///     let inlinedResponse = successResponse.responseValue
+        ///
+        /// You can also look the response up in the `Components`. For convenience, you
+        /// can ask to have the `Either` looked up and the result will be the `Response`
+        /// regardless of whether the `Response` was inlined or found in the `Components`.
+        ///
+        /// **Example:**
+        ///
+        ///     let foundResponse: OpenAPI.Response
+        ///     foundResponse = document.components.dereference(successResponse)!
+        ///
         public var responses: OpenAPI.Response.Map
 //      public let callbacks:
 

Sources/OpenAPIKit/Response/Response.swift

@@ -40,6 +40,28 @@ extension OpenAPI.Response {
     public typealias Map = OrderedDictionary<StatusCode, Either<JSONReference<OpenAPI.Response>, OpenAPI.Response>>
 }
 
+extension OrderedDictionary where Key == OpenAPI.Response.StatusCode {
+    /// This subscript makes it possible to disambiguate the call to the integer-based
+    /// (indexed) subscript and the key-based (hashed) subscript of the `OrderedDictionary`
+    /// for `StatusCode` keys.
+    ///
+    /// A problem of ambiguity arises from the fact that `StatusCode` is `ExpressibleByIntegerLiteral`
+    /// so both `OrderedDictionary` unlabled subscript accessors are applicable.
+    ///
+    /// **Example**:
+    ///
+    ///     let successfulDeleteOperation = document.paths["/hello/world"]?.delete?.responses[status: 204]
+    ///
+    public subscript(status status: OpenAPI.Response.StatusCode) -> Value? {
+        get {
+            return self[status]
+        }
+        set {
+            self[status] = newValue
+        }
+    }
+}
+
 // MARK: - Status Code
 extension OpenAPI.Response {
     /// An HTTP Status code or status code range.

Tests/OpenAPIKitCompatibilitySuite/PetStoreAPITests.swift

@@ -121,7 +121,7 @@ final class PetStoreAPICampatibilityTests: XCTestCase {
         let dereferencedDoc = try apiDoc.locallyDereferenced()
 
         // Pet schema is a $ref to Components Object
-        XCTAssertEqual(dereferencedDoc.paths["/pet"]?.post?.responses[.status(code: 200)]?.content[.json]?.schema.objectContext?.properties["name"]?.underlyingJSONSchema, try JSONSchema.string.with(example: "doggie"))
+        XCTAssertEqual(dereferencedDoc.paths["/pet"]?.post?.responses[status: 200]?.content[.json]?.schema.objectContext?.properties["name"]?.underlyingJSONSchema, try JSONSchema.string.with(example: "doggie"))
     }
 
     func test_resolveDocument() throws {

Tests/OpenAPIKitCompatibilitySuite/TomTomAPITests.swift

@@ -109,7 +109,7 @@ final class TomTomAPICampatibilityTests: XCTestCase {
         let dereferencedDoc = try apiDoc.locallyDereferenced()
 
         // response is a $ref to Components Object
-        XCTAssertEqual(dereferencedDoc.paths["/search/{versionNumber}/cS/{category}.{ext}"]?.get?.responses[.status(code: 200)]?.description, "OK: the search successfully returned zero or more results.")
+        XCTAssertEqual(dereferencedDoc.paths["/search/{versionNumber}/cS/{category}.{ext}"]?.get?.responses[status: 200]?.description, "OK: the search successfully returned zero or more results.")
     }
 
     func test_resolveDocument() throws {

Tests/OpenAPIKitTests/Document/DereferencedDocumentTests.swift

@@ -39,7 +39,7 @@ final class DereferencedDocumentTests: XCTestCase {
         ).locallyDereferenced()
 
         XCTAssertEqual(t1.paths.count, 1)
-        XCTAssertEqual(t1.paths["/hello/world"]?.get?.responses[.status(code: 200)]?.description, "success")
+        XCTAssertEqual(t1.paths["/hello/world"]?.get?.responses[status: 200]?.description, "success")
     }
 
     func test_noSecurityReferencedResponseInPath() throws {
@@ -64,7 +64,7 @@ final class DereferencedDocumentTests: XCTestCase {
         ).locallyDereferenced()
 
         XCTAssertEqual(t1.paths.count, 1)
-        XCTAssertEqual(t1.paths["/hello/world"]?.get?.responses[.status(code: 200)]?.description, "success")
+        XCTAssertEqual(t1.paths["/hello/world"]?.get?.responses[status: 200]?.description, "success")
 
         XCTAssertEqual(t1.routes.first?.path, "/hello/world")
         XCTAssertNotNil(t1.routes.first?.pathItem.get)
@@ -96,7 +96,7 @@ final class DereferencedDocumentTests: XCTestCase {
         ).locallyDereferenced()
 
         XCTAssertEqual(t1.paths.count, 1)
-        XCTAssertEqual(t1.paths["/hello/world"]?.get?.responses[.status(code: 200)]?.description, "success")
+        XCTAssertEqual(t1.paths["/hello/world"]?.get?.responses[status: 200]?.description, "success")
 
         XCTAssertEqual(t1.security.count, 1)
         XCTAssertEqual(t1.security.first?.schemes["test"]?.securityScheme.type, .apiKey(name: "Api-Key", location: .header))

Tests/OpenAPIKitTests/EaseOfUseTests.swift

@@ -454,7 +454,7 @@ final class DeclarativeEaseOfUseTests: XCTestCase {
         let document = testDocument
 
         let endpoint = document.paths["/widgets/{id}"]?.get
-        let response = endpoint?.responses[.status(code: 200)]?.responseValue
+        let response = endpoint?.responses[status: 200]?.responseValue
         let responseSchemaReference = response?.content[.json]?.schema
         // this response schema is a reference found in the Components Object. We dereference
         // it to get at the schema.

Tests/OpenAPIKitTests/Operation/DereferencedOperationTests.swift

@@ -43,7 +43,7 @@ final class DereferencedOperationTests: XCTestCase {
         XCTAssertEqual(t1.parameters.count, 1)
         XCTAssertEqual(t1.requestBody?.underlyingRequest, OpenAPI.Request(content: [.json: .init(schema: .string)]))
         XCTAssertEqual(t1.responses.count, 1)
-        XCTAssertEqual(t1.responseOutcomes.first?.response, t1.responses[.status(code: 200)])
+        XCTAssertEqual(t1.responseOutcomes.first?.response, t1.responses[status: 200])
         XCTAssertEqual(t1.responseOutcomes.first?.status, 200)
     }
 
@@ -137,7 +137,7 @@ final class DereferencedOperationTests: XCTestCase {
             resolvingIn: components
         )
         XCTAssertEqual(
-            t1.responses[.status(code: 200)]?.underlyingResponse,
+            t1.responses[status: 200]?.underlyingResponse,
             .init(description: "test")
         )
     }

Tests/OpenAPIKitTests/Operation/ResolvedEndpointTests.swift

@@ -57,7 +57,7 @@ final class ResolvedEndpointTests: XCTestCase {
         XCTAssertEqual(endpoints.first?.method, .get)
         XCTAssertEqual(endpoints.first?.path, "/hello/world")
         XCTAssertEqual(endpoints.first?.requestBody?.description, "requestBody")
-        XCTAssertEqual(endpoints.first?.responses[.status(code: 200)]?.description, "hello world")
+        XCTAssertEqual(endpoints.first?.responses[status: 200]?.description, "hello world")
         XCTAssertEqual(endpoints.first?.deprecated, true)
 
         let t2 = try OpenAPI.Document(

Tests/OpenAPIKitTests/Path Item/DereferencedPathItemTests.swift

@@ -125,21 +125,21 @@ final class DereferencedPathItemTests: XCTestCase {
 
         XCTAssertEqual(t1.endpoints.count, 8)
         XCTAssertEqual(t1[.delete]?.tags, ["delete op"])
-        XCTAssertEqual(t1[.delete]?.responses[.status(code: 200)]?.description, "delete resp")
+        XCTAssertEqual(t1[.delete]?.responses[status: 200]?.description, "delete resp")
         XCTAssertEqual(t1[.get]?.tags, ["get op"])
-        XCTAssertEqual(t1[.get]?.responses[.status(code: 200)]?.description, "get resp")
+        XCTAssertEqual(t1[.get]?.responses[status: 200]?.description, "get resp")
         XCTAssertEqual(t1[.head]?.tags, ["head op"])
-        XCTAssertEqual(t1[.head]?.responses[.status(code: 200)]?.description, "head resp")
+        XCTAssertEqual(t1[.head]?.responses[status: 200]?.description, "head resp")
         XCTAssertEqual(t1[.options]?.tags, ["options op"])
-        XCTAssertEqual(t1[.options]?.responses[.status(code: 200)]?.description, "options resp")
+        XCTAssertEqual(t1[.options]?.responses[status: 200]?.description, "options resp")
         XCTAssertEqual(t1[.patch]?.tags, ["patch op"])
-        XCTAssertEqual(t1[.patch]?.responses[.status(code: 200)]?.description, "patch resp")
+        XCTAssertEqual(t1[.patch]?.responses[status: 200]?.description, "patch resp")
         XCTAssertEqual(t1[.post]?.tags, ["post op"])
-        XCTAssertEqual(t1[.post]?.responses[.status(code: 200)]?.description, "post resp")
+        XCTAssertEqual(t1[.post]?.responses[status: 200]?.description, "post resp")
         XCTAssertEqual(t1[.put]?.tags, ["put op"])
-        XCTAssertEqual(t1[.put]?.responses[.status(code: 200)]?.description, "put resp")
+        XCTAssertEqual(t1[.put]?.responses[status: 200]?.description, "put resp")
         XCTAssertEqual(t1[.trace]?.tags, ["trace op"])
-        XCTAssertEqual(t1[.trace]?.responses[.status(code: 200)]?.description, "trace resp")
+        XCTAssertEqual(t1[.trace]?.responses[status: 200]?.description, "trace resp")
     }
 
     func test_missingReferencedGetResp() {

Tests/OpenAPIKitTests/Validator/ValidatorTests.swift

@@ -1173,7 +1173,7 @@ final class ValidatorTests: XCTestCase {
 
         let successResponseBodyContainsNameAndId = Validation(
             check: unwrap(
-                \OpenAPI.Response.Map[.status(code: 201)]?.responseValue,
+                \OpenAPI.Response.Map[status: 201]?.responseValue,
                 into: responseBodyContainsNameAndId,
                 description: "201 status response value"
             )
@@ -1301,7 +1301,7 @@ final class ValidatorTests: XCTestCase {
 
         let successResponseBodyContainsNameAndId = Validation(
             check: unwrap(
-                \OpenAPI.Response.Map[.status(code: 201)]?.responseValue,
+                \OpenAPI.Response.Map[status: 201]?.responseValue,
                 into: responseBodyContainsNameAndId,
                 description: "201 status response value"
             )

documentation/validation.md

@@ -496,7 +496,7 @@ let responseBodyContainsNameAndId = Validation(
 // a missing `201` response definition.
 let successResponseBodyContainsNameAndId = Validation(
    check: unwrap(
-       \OpenAPI.Response.Map[.status(code: 201)]?.responseValue,
+       \OpenAPI.Response.Map[status: 201]?.responseValue,
        into: responseBodyContainsNameAndId,
        description: "201 status response value"
     )