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

Generated servers cannot route a path parameter declared `allowReserved: true`

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

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
4/5
预计耗时
3-5 天
新手友好度
48/100
Issue 类型
缺陷
描述清晰度
基本清楚
活跃度
活跃
技术栈
julia, openapi
领域
api, backend

调研方向

阅读 ext/OpenAPIHTTPExt.jl、OpenAPI.server_source，以及生成的服务器 glue 代码使用的 _SERVER_OPS 数据。从 test/servergen.jl 中的 SERVER_ROUNDTRIP_DOCUMENT 开始，并运行现有的服务器生成测试。完成标准是：生成的客户端和服务器能够对 allowReserved 路径值进行 round-trip，而不支持的非末尾 greedy 参数会产生生成时诊断。

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

描述

Summary

Since the runtime honours allowReserved on path parameters, a generated
client sends a slash-delimited path value as multiple path segments. A
generated server built from the same document still registers the raw
template (/documents/{path}), and HTTP.Router matches {name} against
exactly one segment — so the request 404s before it ever reaches
_decode_path_parameter.

One document therefore produces a client and a server that cannot talk to each
other, and the failure is a silent 404 rather than a diagnostic.

Reproduction

Document (3.0 or 3.2 — see the version note below):

"/documents/{path}": {
  "get": {
    "operationId": "getDocument",
    "parameters": [{
      "name": "path", "in": "path", "required": true,
      "allowReserved": true,
      "schema": { "type": "string" }
    }],
    "responses": { "200": { "description": "ok",
      "content": { "text/plain": { "schema": { "type": "string" } } } } }
  }
}

Generate the server, register! it on an HTTP.Router, and dispatch both wire
forms of the value opa/examples/public servers:

/documents/opa%2Fexamples%2Fpublic%20servers  -> 200 got:opa/examples/public servers
/documents/opa/examples/public%20servers      -> 404 <empty>   <-- what the client now sends

Cause

ext/OpenAPIHTTPExt.jl registers the template verbatim:

HTTP.register!(router, entry.method, string(path_prefix, entry.path), handler)

HTTP.Handlers.gethandler splits the request target on / and matches
segment by segment, so {path} is inherently single-segment.

_decode_path_parameter is not at fault — given the full multi-segment raw
text it _percent_decodes to the correct value. Only the route shape is wrong.

Constraints on a fix

  • HTTP.jl's only multi-segment construct is **, and insert! hard-errors
    with "/** double wildcard must be last segment in path". A greedy route is
    therefore only possible when the allowReserved parameter is the final
    path segment. /documents/{path}/versions is unservable this way and should
    raise a generation-time diagnostic rather than emit a silently broken route.
  • ** is not parsed as a Variable, so it contributes nothing to
    HTTP.getparams. The generated handler has to slice the tail out of
    request.target itself.
  • OpenAPI.server_source is a public seam and the HTTP extension is only one
    consumer. The "this operation has a greedy tail parameter" fact belongs in
    _SERVER_OPS (e.g. a greedy_path_arg field) rather than inside
    GENERATED_HTTP_SERVER_GLUE, so other framework extensions do not each
    re-derive it.
  • Not confined to style: simple. label and matrix values span segments
    too (.a/b, ;path=a/b), so those branches of _decode_path_parameter are
    in scope for whatever routing fix lands.
  • allowReserved preserves existing percent-escapes (_escape("%2F"; allow_reserved = true) == "%2F"), so a value whose literal text contains
    %2F is indistinguishable from a separator on the wire. That ambiguity is
    inherent to the feature and should be documented, not worked around.

Tests

SERVER_ROUNDTRIP_DOCUMENT in test/servergen.jl has no allowReserved path
parameter, which is why nothing caught this. A round-trip case there — generated
client target in, generated server handler argument out — is the right place for
the regression test.

Version note

The bundled spec schemas disagree about whether allowReserved is even legal
on a path parameter:

Document version allowReserved on a path parameter
3.0 accepted (generic Parameter property; PathParameter does not forbid it)
3.1 rejected — scoped to styles-for-query under unevaluatedProperties: false; the document fails to load even with strict = false
3.2 accepted, explicitly (styles-for-path)

So this affects 3.0 and 3.2 documents only. The client-side caveat is already
documented in MIGRATION.md and docs/src/clients.md.

主要语言
Julia
星标
56
派生
16
平均合并
1 天 51 分钟
30 天内合并 PR
12

环境准备

这个项目没有提供开发容器、Dockerfile 或贡献指南，环境需要你自己搭建：先看它的 README，通用步骤见我们的新手贡献指南。

从这里开始

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

JuliaComputing/OpenAPI.jl 的其他 Issue

查看 JuliaComputing/OpenAPI.jl 的全部 Issue

相似的 Issue

更多 Julia Issue

把新 issue 发到你的邮箱

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