api - 内部服务器错误是否应该大张旗鼓地记录？

Question

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

标签： apidocumentationswagger-2.0openapi

Answer 1

官方文档显示了在该部分中指定所有 5xx 状态码的示例responses，但没有详细说明特定状态码或返回的消息。它还提到 API 规范应该只包含已知错误：

请注意，API 规范不一定需要涵盖所有可能的 HTTP 响应代码，因为它们可能事先不知道。但是，预计它将涵盖成功的响应和任何已知错误。“已知错误”是指，例如，对于按 ID 返回资源的操作的 404 Not Found 响应，或在操作参数无效的情况下的 400 Bad Request 响应。

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

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