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

Are these OpenAPI 3 paths ambiguous?

Đang mở
  • Có gì không ổn?
#2,564 7 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
25/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

Đọc phần Paths Object trong versions/3.0.0.md và so sánh các quy tắc khớp của phần này với các ví dụ /shops/{shopId}/pets/{petId} và /shops/{shopId}/pets/_search trong issue này. Xem lại phần thảo luận hiện có trước khi quyết định liệu văn bản có cần một định nghĩa hay một ví dụ bổ sung hay không. Công việc được xem là hoàn tất khi các maintainer đồng ý với cách diễn đạt đặc tả đã được làm rõ và phần liên quan được cập nhật.

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

Mô tả

clarification question request matching

As suggested by @MikeRalphson on Stackoverflow, I'm asking the question here as well.

Are those OpenAPI 3 paths ambiguous?

/shops/{shopId}/pets/{petId}   
/shops/{shopId}/pets/_search

I want to answer no but, strictly reading the spec, I can't decide because they seem to fall into none of the 3 statements made by the spec:

  1. Neither path is concrete (term used in the spec)
  2. Paths don't seem to meet the Templated paths with the same hierarchy but different templated names criteria (that is not very clear to me, here is my understanding: "/shops/{}/pets/{}" != "/shops/{}/pets/_search")
  3. Paths do not look like the ambiguous example

In addition to the question asked on Stackoverflow, let me ask two additional questions (below).

Should the OA3 spec be improved?

@MikeRalphson's reading of the spec: path are not ambiguous because one is more concrete than the other.

If paths are indeed not ambiguous, then the more concrete notion might need to be defined.

How could the OA3 spec be improved?

We might add an example like this:

Assuming paths sharing a common and identical prefix, /shops/{shopId}/pets, the more concrete definition, /shops/{shopId}/pets/_search, will be matched first if used:

  /shops/{shopId}/pets/{petId}
  /shops/{shopId}/pets/_search

Or we might only show minimalistic examples involving templated names, and say that they also apply in case of common and identical prefixes:

First statement (concrete vs template case):

  /{otherPlace}
  /here

Second statement (considered identical and invalid):

  /{id}
  /{name}

Third statement is left unchanged (ambiguous resolution):

/{entity}/me
/books/{id}

Related excerpt of the OA3 spec

The "Paths object" paragraph of the OpenAPI 3 specification (https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#paths-object) is stating (3 sentences, 3 statements):

When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use.

Those 3 statements are followed by 3 examples (and that's it):

Assuming the following paths, the concrete definition, /pets/mine, will be matched first if used:

  /pets/{petId}
  /pets/mine

The following paths are considered identical and invalid:

  /pets/{petId}
  /pets/{name}

The following may lead to ambiguous resolution:

/{entity}/me
/books/{id}
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.