Handle 3XX redirection

[danielsharvey]

Would it be possible to have the 3XX case fall through/follow the same behaviour as the 2XX case?

openapi-ts/packages/openapi-ts/src/ir/operation.ts

Lines 127 to 143 in 3d17490

	switch (statusCodeToGroup({ statusCode: name })) {
	case '1XX':
	case '3XX':
	// TODO: parser - handle informational and redirection status codes
	break;
	case '2XX':
	responses.properties[name] = response.schema;
	break;
	case '4XX':
	case '5XX':
	errors.properties[name] = response.schema;
	break;
	case 'default':
	defaultResponse = response;
	break;
	}
	}

My use case:

1. POST to create filter route /apps/filters
2. On success this route returns a HTTP/303 See Other which redirects to the first page of the GET /apps/filters/{filterId}
3. The Fetch client correctly follows the redirect, but the generated SDK does not include the type for the returned response after the redirect.

I am not sure of the "official" mechanism for handling this response type issue in OpenAPI, but I know of several suggestions. See below.

My preference is the first option as this looks to work with and Redocly/Stoplight/etc and works with openapi-ts if the change described above is made.

Document the "effective response" (after redirecting) alongside the 303

Specifically, add the HTTP/303 Location redirect and the target content response object together. This works in openapi-ts if the 3XX behaves the same as the 2XX in the code above.

e.g.

paths:
  /example:
    post:
      responses:
        '303':
          description: On success will redirect to `getByFilterId` (client will automatically follow redirect, response object referenced below)
          headers:
            Location:
              schema:
                type: string
              description: URI of the created filter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActualResponse'

Use response composition with oneOf/anyOf:

This is understandable by humans but openapi-ts and Redocly/Stoplight/etc don't handle this well.

paths:
  /example:
    get:
      responses:
        '303':
          description: See Other with automatic redirect
          oneOf:
            - $ref: '#/components/responses/RedirectResponse'
            - $ref: '#/components/responses/ActualResponse'

Include Object Links

Either could also include Links | Swagger Docs although I am not sure how well supported this is to date.

e.g.

paths:
  /example:
    post:
      responses:
        '303':
          description: On success will redirect to `getByFilterId` (client will automatically follow redirect, response object referenced below)
          headers:
            Location:
              schema:
                type: string
              description: URI of the created filter.
          links:
            address:
              operationId: getAppsByFilterId
              parameters:
                userId: $response.body#/id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActualResponse'

Note that 3XX is also included in isErrorStatusCode(), which I think is not correct (though I've not followed the logic of how openapi-ts uses this function).

openapi-ts/packages/openapi-ts/src/openApi/common/parser/operation.ts

Lines 99 to 103 in 3d17490

	const isErrorStatusCode = (code: OperationResponse['code']) =>
	code === '3XX' ||
	code === '4XX' ||
	code === '5XX' ||
	(typeof code === 'number' && code >= 300);

[mrlubos]

Hey @danielsharvey, love this! Yeah this should and will be added. You're also right it's not really an OpenAPI spec concern, but I agree with the implementation

[mrlubos]

@danielsharvey any chance you can give me a working API to test this against?

[danielsharvey]

@mrlubos Apologies for missing this. I can provide an example. Are OK to need auth? (I can provide full instructions)

[mrlubos]

@danielsharvey totally up to you! You can contact me privately if it's something that shouldn't be shared here

[danielsharvey]

@mrlubos Hectic week at work. I will provide details today.

[mrlubos]

Absolutely no rush!