是否应该大摇大摆地记录内部服务器错误？
Should Internal Server Error be documented in swagger?
我正在编写一个新的 API 并使用 Swagger/OpenAPI 对其进行记录。记录错误响应似乎是一个很好的标准，开发人员可能会遇到这种情况。
但是我找不到任何关于内部服务器错误的指南或最佳实践。理论上，每条路径都可能引发未处理的异常。我不希望它发生，但它可能会发生。所有路径都应该有状态代码 500 的响应 "Internal Server Error" 还是我应该只记录开发人员可以做任何事情的响应，即 2xx、3xx 和 4xx？
官方文档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 错误代码的响应也是有意义的。
我正在编写一个新的 API 并使用 Swagger/OpenAPI 对其进行记录。记录错误响应似乎是一个很好的标准，开发人员可能会遇到这种情况。 但是我找不到任何关于内部服务器错误的指南或最佳实践。理论上，每条路径都可能引发未处理的异常。我不希望它发生，但它可能会发生。所有路径都应该有状态代码 500 的响应 "Internal Server Error" 还是我应该只记录开发人员可以做任何事情的响应，即 2xx、3xx 和 4xx？
官方文档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 错误代码的响应也是有意义的。