Menu
As far as I checked on many swagger files of Amazon/Google and more, That error code (or generally error codes of 5xx family) is not shown as a part of the swagger files. Is their a reason for that?
I am asking because one of our microservices API returns 500 when it fails to communicate to other service (for instance) and we are wondering if that error code should be part of our swagger files.
719
IMO the correct answer is read the API documentation, try to retry on errors specificially indicated as retryable, and don't blindly retry on generic 500 until you've weighed the pros and cons. Most web services document how their API works at a more granular level than HTTP status codes.
You can use an API design tool to define your API in the Swagger (OpenAPI) specification as follows: Notice the data types and an example described in each response item an end user can expect from a successful GET call. The successful response an end user would receive in JSON would look as follows. ….
The integration allows developers to automatically host and visualize their API documentation on SwaggerHub to enable API discovery and consumption by internal and external stakeholders. Head over to Swagger Inspector, and insert the end point of the resource you want to have documented.
Reason: Internal Server Error Hi @jessedc - per the Swagger specification, each operation must contain at least one response (either numeric or default and that response must have at least a description ). Without it, the definition you have is malformed as far as validation goes.
Generally clients/consumers can't do much upon getting the 5xx errors, since those are purely server side errors. So it need not to be part of your API specification.
If you think, based on the error which the API throws, client/consumer should do something (For example retry or try another site or so.), then Yes.
136
I think API documentation should only contain expected errors such as 4xx ones. But 5xx are unexpected errors and should not be documented.
25
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
