Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

The Response object's `default` field is confusing and inconsistently interpreted

未关闭
  • 哪里不对？
#3,396 9 条评论 1 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
28/100
Issue 类型
文档
描述清晰度
基本清楚
活跃度
停滞
技术栈
openapi
领域
api, documentation

调研方向

首先查看 examples/v3.0/petstore-expanded.yaml 以及 OpenAPI 3.0 和 3.1 的 Response 对象定义。将文档中说明的 default 含义与示例预期的错误处理进行比较，然后确定哪种澄清或示例更新是可行的；完成这项工作需要就对规范或示例的变更达成一致。

由索引模型根据 Issue 内容生成。

描述

clarification re-use: globals/defaults

According both 3.0 and 3.1, in theResponse object there MUST be at least one response code and it SHOULD be the response for a successful operation call. In addition the default describes “responses other than the ones declared for specific HTTP response codes”.

This means that if we had a 200 response and default, the latter would cover everything except for 200. Many seem to interpret default to mean something like response categories not covered by explicit response codes. Consider this example from the OAI org:

responses:
        '200':
          description: pet response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore-expanded.yaml

This implies that default covers error types when in fact it covers non-error responses as well. In fact, the consumer wouldn't necessarily know if the API might reply with another success code such as a 204. A more precise example might look like this:

responses:
        '200':
          description: pet response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        4xx:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5xx:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

I would suggest the following actions:

  1. Update the example to interpret the spec more literally
  2. Clarify default since this confusion is not limited to this example, but extends to APIs in the wild
  3. Consider in 3.2 or 4.0 eliminating default
  4. Consider in 3.2 or 4.0 adding a new named error category that means "both 4xx and 5xx". This could be used in the way that default is often misused today
主要语言
Markdown
星标
31.2k
派生
9.2k
平均合并
2 天 9 小时
30 天内合并 PR
17

环境准备

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

OAI/OpenAPI-Specification 的其他 Issue

查看 OAI/OpenAPI-Specification 的全部 Issue

相似的 Issue

更多 Backend & API Design Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。