fix(codegen): don't surface error responses as method return types

[erunion]

🚥 Fixes #612

🧰 Changes

This fixes a problem in codegen where we're documenting 400 and 500 status code families as being possible return types for SDK methods which is not accurate as when we encounter these status codes we throw a FetchError. This is causing codegen's responses for these methods to effectively be typed as unknown as noted here¹.

Unfortunately for us TypeScript doesn't offer any way to document that a method may throw an exception, and what that exception contains, so we need to fallback to a JSDoc @throws annotation. Not great but other than completely removing those error response types from the compiled SDK, which I don't want to do, we don't have any other option.

I have also cleaned up another very minor thing in this work with regard to typed method overloads that we're creating for methods that have an optional body or metadata. In these cases Because the first argument of the method can be either body or metadata we're creating a typed TS overload² for each alternative. We were adding a docblock to each of these overloads but in actuality IDE Intellisense only ever picks up the docblock from the first method so adding the same docblock not only increases the size of the SDK we're generating but also fills the SDK with documentation that just isn't being used.

🧬 QA & Testing

The status code work is pretty well tested here with the SDK fixture snapshots we've got but for the docblock work you can see how the docblock from the first overload of this method is being picked up by Intellisense:

For comparison, if we add that docblock to the last method it doesn't get picked up:

Footnotes

1. https://github.com/readmeio/api/issues/612#issuecomment-1633949991 ↩

2. https://www.typescriptlang.org/docs/handbook/2/functions.html#function-overloads ↩

[domharrington]

LGTM!