Add tests for responses with examples

[simonjbeaumont]

Motivation

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

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:

  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³.

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.

Footnotes

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 ↩

[czechboy0]

Interesting – @mattpolzin, is it intentional that the value property on Example is non-optional?

Here's a link for 3.0.0-alpha.9 and OpenAPIKit30: https://github.com/mattpolzin/OpenAPIKit/blob/3.0.0-alpha.9/Sources/OpenAPIKit30/Example.swift#L20

[mattpolzin]

Looks like an oversight to me. I'm a bit surprised that an example with no "example" is useful, but I'm no less beholden to the spec!

Tracked as bug here.