tripletex-api2 icon indicating copy to clipboard operation
tripletex-api2 copied to clipboard

Specify additional known responses other than 200 OK in swagger schema

Open thhermansen opened this issue 2 years ago • 0 comments

Tripletex's schema describes 200 OK responses, like this:

image

but it is lacking in regards to describing the other expected responses like 401, 422 etc. This results in generated clients[^2] not knowing of all responses an operation may yield, in this case it has no knowledge of any errors:

image

If I understand swagger's doc^1 correctly it would be appropriate to include other common responses too:

Note that an API specification does not necessarily need to cover all possible HTTP response codes, since they may not be known in advance. However, it is expected to cover successful responses and any known errors. By "known errors" we mean, for example, a 404 Not Found response for an operation that returns a resource by ID, or a 400 Bad Request response in case of invalid operation parameters.

[^2]: Example https://openapi-ts.pages.dev/

thhermansen avatar Oct 26 '23 13:10 thhermansen