2 ms·
pathResponses: notFound: status: 404 contentType: application/http-problem apiResponses: serverError: status: 5XX
by londons_explore 3y ago
pathResponses:
notFound:
status: 404
contentType: application/http-problem
apiResponses:
serverError:
status: 5XX
contentType: application/http-problem
Can't stuff like this be implicit rather than needing to be defined? Or, to say it another way, we're building this over HTTP, which already defines these things and many others.
- djbusby 3y agoUgh, or try having a mostly common response with just a slight mutation (eg the data is array of Company rather than Contact). Verbose for what could be a "mixing" or "sub-class" or something.
- kelnos 3y agoOpenAPI does support "subclassing" via allOf and oneOf.
- junto 3y agoIt’s explicit in the responses you should expect for a given request, versus what you should expect. For example if the specification defined that a 404 is a valid use case then null or empty list is not considered an exception, but if it isn’t defined in the spec and you receive a 404 unexpectedly, then you can treat it as an exception rather than a valid response.
- cies 3y agoExactly. Also you want to be able to give, for instance, 400s a body that's JSON schema'd
- contravariant 3y agoThis way you can provide a schema for the error such that a client can parse the response. It makes sense for an API schema to include it.
- eyelidlessness 3y agoThis. And it may not be immediately obvious if you’re not familiar with RFC 7807, but in the example the responses’ content types specify their schema.