设计 api - 我们是否应该在开放 api 规范中包含 4xx 响应？
Designing an api - should we include 4xx responses or not in open api specification?
在设计 GET 端点时我很困惑......
设计了 Open API spec 3.0 成功响应（200），无效请求（缺少强制性内容）（400）
现在我对以下内容感到困惑：401（未经授权）、405（方法不允许）、415（不支持的媒体类型）
此 API 需要在 header 中提供一个 api 密钥，如果用户未提供或提供了无效的 api 密钥，则他们应该得到一个 401
所以我认为我应该在我的响应规范中指定 401。
但是，当我查看 swagger 的宠物商店 ( https://editor.swagger.io/ ) 时，他们在任何地方都没有此响应代码......?
我的 API 规范仅支持 Content-type 的 GET：application/json 所以我认为我们不需要 405（DELETE/POST/PUT 等）。
同样，如果消费者发送 application/xml 或 application/json 以外的任何内容，我们不支持它，所以这就是为什么我们不应该在规范中明确定义 415 ?
我认为记录 API 可能 return 的响应代码是个好主意，OpenAPI 确实 supported（但可选）。
消费者可能会发现了解 401 未授权意味着未提供 JWT 令牌或已过期，或者 400 意味着有效负载不正确（即缺少特定属性）。
如果您想查看 Swagger 如何记录和显示响应代码，请选中此 example UI。
However when I look at swagger's Pet store they are not having this response code anywhere ... ?
Pet Store 实际上只是一个示例，您可以将其用作起点，或者当您想为工具提供样本规格时。它并不意味着规范。如果您查看示例代码，您甚至会发现 RPC 风格的路径 (e.g. here) 和其他不完全 RESTful.
的东西
why we should not be explicitly defining 415 in the spec ?
我认为您找到的博文很有帮助，而且并不矛盾。他们都正确地建议您使用标准的 http 响应代码并提供有用的错误正文。有些人省略了他们认为是 self-explanatory 的响应代码。但是 IMO，添加这几行是完全值得的。如果你努力添加它们，那么你就会得到 openapi 的一个关键方面：openapi 的目的是明确和可预测你的 API.[=13 的功能和行为=]
总而言之：是，考虑一下您将需要的回复，然后在您的回复代码中包含这些回复代码 api规格
在设计 GET 端点时我很困惑...... 设计了 Open API spec 3.0 成功响应（200），无效请求（缺少强制性内容）（400）
现在我对以下内容感到困惑：401（未经授权）、405（方法不允许）、415（不支持的媒体类型）
此 API 需要在 header 中提供一个 api 密钥，如果用户未提供或提供了无效的 api 密钥，则他们应该得到一个 401 所以我认为我应该在我的响应规范中指定 401。 但是，当我查看 swagger 的宠物商店 ( https://editor.swagger.io/ ) 时，他们在任何地方都没有此响应代码......?
我的 API 规范仅支持 Content-type 的 GET：application/json 所以我认为我们不需要 405（DELETE/POST/PUT 等）。 同样，如果消费者发送 application/xml 或 application/json 以外的任何内容，我们不支持它，所以这就是为什么我们不应该在规范中明确定义 415 ?
我认为记录 API 可能 return 的响应代码是个好主意，OpenAPI 确实 supported（但可选）。
消费者可能会发现了解 401 未授权意味着未提供 JWT 令牌或已过期，或者 400 意味着有效负载不正确（即缺少特定属性）。
如果您想查看 Swagger 如何记录和显示响应代码，请选中此 example UI。
However when I look at swagger's Pet store they are not having this response code anywhere ... ?
Pet Store 实际上只是一个示例，您可以将其用作起点，或者当您想为工具提供样本规格时。它并不意味着规范。如果您查看示例代码，您甚至会发现 RPC 风格的路径 (e.g. here) 和其他不完全 RESTful.
的东西why we should not be explicitly defining 415 in the spec ?
我认为您找到的博文很有帮助，而且并不矛盾。他们都正确地建议您使用标准的 http 响应代码并提供有用的错误正文。有些人省略了他们认为是 self-explanatory 的响应代码。但是 IMO，添加这几行是完全值得的。如果你努力添加它们，那么你就会得到 openapi 的一个关键方面：openapi 的目的是明确和可预测你的 API.[=13 的功能和行为=]
总而言之：是，考虑一下您将需要的回复，然后在您的回复代码中包含这些回复代码 api规格