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

【问题标题】：Should Internal Server Error be documented in swagger?内部服务器错误是否应该大张旗鼓地记录？
【发布时间】：2019-03-04 18:26:57
【问题描述】：

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

【问题讨论】：

标签： api documentation swagger-2.0 openapi

【解决方案1】：

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

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

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

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

【讨论】：

我认为你省略它是对的。我最近还阅读了 OWASP 关于 A6:2017 - Security Misconfiguration 的建议，其中指出自动爬虫使用 5xx HTTP 错误代码来继续探测，因为这可能是配置错误的迹象。
是的，我也觉得只有调试的时候才好，生产中应该避免。