Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

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

Đang mở
  • Có gì không ổn?
#3,396 9 bình luận 1 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
28/100
Loại issue
Tài liệu
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
openapi
Lĩnh vực
api, documentation

Hướng nghiên cứu

Bắt đầu bằng việc xem xét examples/v3.0/petstore-expanded.yaml và các định nghĩa đối tượng Response cho OpenAPI 3.0 và 3.1. So sánh ý nghĩa được tài liệu hóa của default với cách xử lý lỗi mà ví dụ hướng đến, sau đó xác định việc làm rõ hoặc cập nhật ví dụ nào là khả thi; để hoàn tất sẽ cần có một thay đổi được thống nhất đối với đặc tả hoặc các ví dụ.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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
Ngôn ngữ chính
Markdown
Star
31.2k
Fork
9.2k
Merge trung bình
2 ngày 9 giờ
Pull request đã merge (30 ngày)
17

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của OAI/OpenAPI-Specification

Tất cả issue của OAI/OpenAPI-Specification

Issue tương tự

Thêm issue về Backend & API Design

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.