feat: include all status code and media types in response body union

[christoph-fricke]

This PR changes how response bodies are mapped. Previously, it should have chosen the first 2XX status code with the first media type, according to the JSDocs from openapi-typescript-helpers. However, the JSDocs comments are a lie as the types pick the union of all 2XX responses with all media types. This causes problems with specs where different media types are used across multiple status codes (see the following example). It results in a response typing of StrictResponse<null> instead of StrictResponse<{ /* ... */} | string>.

/resource:
    get:
      summary: Get Resource
      operationId: getResource
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Resource"
        202:
          description: Accepted
          content:
            text/plain:
              schema:
                type: string

With this PR, the strict response is now properly typed with a union of all available response bodies, e.g. StrictResponse<{ /* ... */} | string>. Since we already have a union of all successful responses anyway, I decided to extend it to also include the response bodies of status codes, i.e. error responses as well. This has been suggested in #38.

However, this change also has one downside. Imagine an endpoint that returns an entity on success and a error object on error. Previously, while writing the response object in an handler, the editor would only suggest keys for the entity object. With this PR the editor will now suggest keys from both the entity and error object. Even when the return response body already contains keys that are only available in the entity, the editor will continue to suggest keys from the error object. Thankfully, at least the type check still works as expected and detects responses that do not fulfill the expected schema.

Until we ship #41, this makes it harder to easily type response bodies on the fly as you mentally have to filter irrelevant suggestions.

[changeset-bot]

🦋 Changeset detected

Latest commit: 4d615f6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
openapi-msw	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[margalit]

Ah interesting!

I think this is a good trade-off as a union of all possible response types unlocks the ability to mock more response scenarios, even if they aren’t the most common ones. This seems to be closer to how the openapi-fetch api works too.

I think it’s a good trade-off, especially considering the possibility of adding a response helper like the one detailed here.

[christoph-fricke]

There is currently an open problem for status codes that return no content, i.e.:

responses:
  200:
    description: Success
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/Resource"
  204:
    description: NoContent

The result in the typing StrictReponse<null> instead of a union with { /* content */ } | null.

[christoph-fricke]

@margalit @luchsamapparat Thank you for your feedback! I will give this a final review and release the change tomorrow. 🚀