api - 内部服务器错误是否应该在 swagger 中记录？

Question

我正在编写一个新的 API 并使用 Swagger/OpenAPI 对其进行记录。记录错误响应似乎是一个很好的标准，开发人员可能会遇到。
但是我找不到关于内部服务器错误的任何指导方针或最佳实践。理论上，每条路径都可能抛出未处理的异常。我不希望它发生，但它可能会发生。所有路径都应该有一个状态代码为 500“内部服务器错误”的响应，还是我应该只记录开发人员可以做任何事情的响应，即 2xx、3xx 和 4xx？

Answer 1

官方文档 shows an example用于指定 responses 中的所有 5xx 状态代码部分，但它没有详细介绍特定的状态代码或返回的消息。它还提到 API 规范应该只包含已知错误:

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.

您可以遵循相同的方法并像示例中那样指定它。我认为尝试更具体地描述它并不重要，甚至不建议尝试更具体地描述它，因为无论如何您可能无法涵盖所有​​情况，并且预计客户端不会对因内部服务器错误返回的消息采取行动(可能不是稍后重试) .例如，我不建议为其指定消息格式。

省略任何带有 5xx HTTP 错误代码的响应也是有意义的。