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

Question

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

Answer 1

官方文档在本节中给出了指定所有 5xx 状态码的示例responses，但没有详细介绍具体的状态码或返回的消息。它还提到 API 规范应该只包含已知错误：

\n\n

\n

请注意，API 规范不一定需要涵盖所有可能的 HTTP 响应代码，因为它们可能无法提前获知。但是，预计它会涵盖成功的响应和任何已知的错误。对于 \xe2\x80\x9cknown 错误\xe2\x80\x9d，我们指的是，例如，针对按 ID 返回资源的操作的 404 Not Found 响应，或者在操作参数无效的情况下的 400 Bad Request 响应。

\n

\n\n

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

\n\n

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

\n