Consider additional guidance on Server Objects
维护者通常 1 天内回复
还没有人认领这个 Issue。
评估
- 难度
- 4/5
- 预计耗时
- 3-5 天
- 新手友好度
- 35/100
- Issue 类型
- 文档
- 描述清晰度
- 基本清楚
- 活跃度
- 停滞
- 技术栈
- openapi
调研方向
从 Learn Site 的 Server Object 页面开始，审查 PR #4389 中提出的问题，尤其是关于相对服务器 URL、检索 URI 和服务器变量的说明。完成的标准是确定这些指导应放在哪里，并在 Learn Site 或规范文档中清楚记录相关注意事项。
由索引模型根据 Issue 内容生成。
描述
@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.
- 主要语言
- Markdown
- 星标
- 31.2k
- 派生
- 9.2k
- 平均合并
- 2 天 9 小时
- 30 天内合并 PR
- 17
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 Issue 编号。
OAI/OpenAPI-Specification 的其他 Issue
-
Housekeeping
难度 1/5 1 小时以内 新手友好度 45/100
OAI/OpenAPI-Specification#5566 ·
维护者通常 1 天内回复
-
Housekeeping
难度 1/5 1 小时以内 新手友好度 35/100
OAI/OpenAPI-Specification#5562 · 4 条评论 ·
维护者通常 1 天内回复
-
Housekeeping
难度 5/5 一周以上 新手友好度 10/100
OAI/OpenAPI-Specification#5556 · 3 条评论 ·
维护者通常 1 天内回复
-
v3.2.1 release可能重新可做 @lornajane 于 32 天前认领，目前没有进行中的 PR。 未关闭
OAI/OpenAPI-Specification#5460 · 11 条评论 · 1 个 reaction · 已指派 1 人 ·
维护者通常 1 天内回复
-
param serialization
难度 5/5 一周以上 新手友好度 25/100
OAI/OpenAPI-Specification#5366 · 12 条评论 ·
维护者通常 1 天内回复
查看 OAI/OpenAPI-Specification 的全部 Issue
相似的 Issue
-
难度 1/5 1 小时以内 新手友好度 66/100
monero-project/monero-docs#430 · 3 条评论 ·
维护者通常 6 天内回复
-
难度 1/5 1 小时以内 新手友好度 67/100
navikt/esyfo-narmesteleder#700 ·
维护者通常 1 天内回复
-
area: agents area: docs good first issue
难度 2/5 1-3 小时 新手友好度 88/100
openapi/gknowledge#23 ·
-
agent-review-finding bug
难度 2/5 1-3 小时 新手友好度 68/100
jordansmall/spindrift#5281 ·
维护者通常 1 天内回复
-
[quality] Nothing keeps docs/skills/manifest.md in sync with docs/skills/*.md可能已有人在做 @hivecommons-hive 今天认领。 未关闭agent/quality hive/covered-by-pr hive/hosted-available-lke648397-260827-5n31 quality testing
难度 2/5 1-3 小时 新手友好度 78/100
维护者通常 1 天内回复