Add tests for responses with examples (#166)

### Motivation

The OpenAPI specification allows for specifying examples along side a
schema in a content map[^1]. The example can be an object with some
defined fields, but none of these fields are mandatory in OpenAPI
3.0.3[^2].

However, it looks like we're failing to parse documents that don't have
the `value` field.

Specifically we can't parse this spec unless we add the `value` field:

```diff
  responses:
    MyResponse:
      description: Some response
      content:
        application/json:
          schema:
            type: string
          examples:
            application/json:
              summary: "a hello response"
+             value: "hello"
```

This is used in the wild—notably in the Github API.

This appears to be because the model used in OpenAPIKit expects `value`
to be non-optional[^3].

### Modifications

Add some tests, one with an `XCTExpectFailure`, to track this.

### Result

We have tests that we can use to track this incompatibility with such
OpenAPI documents.

### Test Plan

This patch is tests only.

[^1]: https://spec.openapis.org/oas/v3.0.3#mediaTypeObject
[^2]: https://spec.openapis.org/oas/v3.0.3#exampleObject
[^3]:
https://github.com/mattpolzin/OpenAPIKit/blob/main/Sources/OpenAPIKit/Example.swift#L19

---------

Signed-off-by: Si Beaumont <[email protected]>

Author: simonjbeaumont

Tests/OpenAPIGeneratorReferenceTests/SnippetBasedReferenceTests.swift

@@ -772,6 +772,85 @@ final class SnippetBasedReferenceTests: XCTestCase {
             )
         )
     }
+
+    func testResponseWithExampleWithSummaryAndValue() throws {
+        try self.assertResponsesTranslation(
+            """
+            responses:
+              MyResponse:
+                description: Some response
+                content:
+                  application/json:
+                    schema:
+                      type: string
+                    examples:
+                      application/json:
+                        summary: "a hello response"
+                        value: "hello"
+            """,
+            """
+            public enum Responses {
+                public struct MyResponse: Sendable, Equatable, Hashable {
+                    public struct Headers: Sendable, Equatable, Hashable { public init() {} }
+                    public var headers: Components.Responses.MyResponse.Headers
+                    @frozen public enum Body: Sendable, Equatable, Hashable {
+                        case json(Swift.String)
+                    }
+                    public var body: Components.Responses.MyResponse.Body
+                    public init(
+                        headers: Components.Responses.MyResponse.Headers = .init(),
+                        body: Components.Responses.MyResponse.Body
+                    ) {
+                        self.headers = headers
+                        self.body = body
+                    }
+                }
+            }
+            """
+        )
+    }
+
+    func testResponseWithExampleWithOnlyValue() throws {
+        // This test currently throws because the parsing of ExampleObject is too strict:
+        // https://github.com/mattpolzin/OpenAPIKit/issues/286.
+        XCTAssertThrowsError(
+            try self.assertResponsesTranslation(
+                """
+                responses:
+                  MyResponse:
+                    description: Some response
+                    content:
+                      application/json:
+                        schema:
+                          type: string
+                        examples:
+                          application/json:
+                            summary: "a hello response"
+                """,
+                """
+                public enum Responses {
+                    public struct MyResponse: Sendable, Equatable, Hashable {
+                        public struct Headers: Sendable, Equatable, Hashable { public init() {} }
+                        public var headers: Components.Responses.MyResponse.Headers
+                        @frozen public enum Body: Sendable, Equatable, Hashable {
+                            case json(Swift.String)
+                        }
+                        public var body: Components.Responses.MyResponse.Body
+                        public init(
+                            headers: Components.Responses.MyResponse.Headers = .init(),
+                            body: Components.Responses.MyResponse.Body
+                        ) {
+                            self.headers = headers
+                            self.body = body
+                        }
+                    }
+                }
+                """
+            )
+        ) { error in
+            XCTAssert(error is DecodingError)
+        }
+    }
 }
 
 extension SnippetBasedReferenceTests {