知识卡片
通用错误响应复用定义
多个端点若返回同一种 404 等错误,可以在 components.responses 中定义一次,再由各操作引用。错误载荷本身也能用独立 Error 模式描述。复用让响应结构一致,同时各端点仍明确列出自己可能返回的状态码。
这张卡片看不懂?
这张卡片的反馈已满 10 条,暂时无法继续提交。
已有反馈 · 0 / 10 条
还没有人提交反馈。
原书出处
参考来源
- 位置:《Microservice APIs》第 5 章《Documenting REST APIs with OpenAPI》(源文件:_epub-src/OEBPS/Text/05.htm)
- 结论依据:原文在 components.responses 定义 NotFound,再在 GET 订单端点的 404 下用 `$ref` 引用,并说明相同响应可复用。
- 原始内容:We define generic responses within the responses header of the API’s components section. ... This specification for the 404 response can be reused in the specification of all our endpoints under the /orders/{order_id} URL path, since all of those endpoints are specifically designed to target a specific resource .