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

Consider additional guidance on Server Objects

Đang mở
  • Có gì không ổn?
#4,542 0 bình luận 0 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ó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
35/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
documentation

Hướng nghiên cứu

Bắt đầu với trang Server Object của Learn Site và xem xét các mối quan ngại được nêu trong PR #4389, đặc biệt là các ghi chú về URL máy chủ tương đối, URI truy xuất và biến máy chủ. Công việc được xem là hoàn tất khi đã quyết định hướng dẫn này nên được đặt ở đâu và các điểm cần lưu ý liên quan được ghi lại rõ ràng, είτε trên Learn Site hoặc trong tài liệu đặc tả.

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

Mô tả

deployment

@karenetheridge and @notEthan raised various points about confusion and usage of the Server Object and its url field in PR #4389.

From @karenetheridge

We can also offer caution that if server urls are not absolute, then the retrieval URI will be used to resolve them, which might not be desirable because if the scheme+host of the retrieval URI may not actually be the same scheme+host as where the APIs are being hosted, the result will be that any matching of API HTTP requests against path-items in the OpenAPI document will fail.

This caveat is not new with these changes, but a user might think that an absolute $self is sufficient to ward off this problem, which it isn't.

From @notEthan (the part about server variables vs relative server URLs being the most relevant to this issue, see #4541 for other concerns raised in this quote):

I certainly agree/understand that the URIs of the API description and objects within are quite different than (or unrelated to) API server/endpoint URLs. My hesitation is on the idea that the retrieval URI for the OAD is likely to be more closely related to the server URL than $self (I've generally seen the OAD served from one place accompanying documentation, not with each deployment, and aren't server variables the better mechanism for deployment-specific URLs?).

Or rather, my hesitation as an implementer of tooling is on whether that difference is worth implementing - I have one base URI for objects in the OAD (including servers), which will be changing to inherit from $self, and no place to put another base URI. It's not difficult to implement but it adds some complexity in a place I have doubts on the real utility of it.

Note that some of this guidance could go on the Learn Site, which already has a substantial page on the Server Object.

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ề Documentation

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.