内部错误 (500) 是不是应该成为 Swagger API 文档的一部分？

Posted 2023-03-08

【中文标题】内部错误 (500) 是不是应该成为 Swagger API 文档的一部分？

【英文标题】：Should Internal error (500) be part of Swagger API documentation?内部错误 (500) 是否应该成为 Swagger API 文档的一部分？

【发布时间】：2019-06-11 19:40:12

【问题描述】：

据我检查 Amazon/Google 等的许多 swagger 文件，该错误代码（或通常是 5xx 系列的错误代码）并未显示为 swagger 文件的一部分。这是他们的原因吗？ 我之所以这么问，是因为我们的一个微服务 API 在无法与其他服务通信（例如）时返回 500，我们想知道该错误代码是否应该成为我们的 swagger 文件的一部分。

【参考方案1】：

一般而言，客户端/消费者在收到 5xx 错误时无能为力，因为这些纯粹是服务器端错误。所以它需要不成为您的 API 规范的一部分。

如果您认为，基于 API 抛出的错误，客户端/消费者应该做一些事情（例如重试或尝试另一个站点等），那么是的。

【讨论】：

好的，谢谢。如果您说 5xx 错误通常不是可接受的错误，那么如果我的微服务无法与其他服务通信（例如，在网络故障的情况下），我的微服务应该返回什么错误代码？

我没有说 5XX 错误通常是不可接受的。如果发生服务器端错误，API 应该以 5xx 错误响应。我的意思是，它不应该是 API 规范共享的一部分与消费者/客户。

【参考方案2】：

我认为 API 文档应该只包含预期的错误，例如 4xx 错误。但 5xx 是意外错误，不应记录在案。