[Feature Request] HTTP: declare custom/extended HTTP methods and emit OpenAPI 3.2 additionalOperations

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

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
35/100
Issue 类型
功能
描述清晰度
需要澄清
活跃度
冷清
技术栈
openapi
领域
api, backend-api-design

调研方向

从 @typespec/http 的 HttpVerb 和 HttpOperation 模型开始，然后跟踪 @typespec/openapi3 的 OpenAPIPathItem3_2 以及 path-item 的生成。确认目标版本如何选择，以及 diagnostics 如何报告。完成的标准是：可以声明自定义方法，将其暴露给 emitters，为 OpenAPI 3.2 生成为 additionalOperations，并针对不受支持的目标生成诊断。

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

描述

design:needed emitter:openapi3 lib:http triaged:core
Clear and concise description of the problem

OpenAPI 3.2 added the additionalOperations field on the Path Item Object, so a document can now describe operations using HTTP methods outside the classic eight (WebDAV's PROPFIND/PROPPATCH/MKCOL/MOVE/COPY/LOCK, LINK/UNLINK, vendor methods, etc.), alongside the new first-class query method (#11171 tracks QUERY specifically).

TypeSpec currently cannot express such operations at all:

  • @typespec/http's HttpVerb is the closed union "get" | "put" | "post" | "patch" | "delete" | "head", and there is no decorator to declare any other method.
  • @typespec/openapi3 (1.15.0) already ships the 3.2 output types — OpenAPIPathItem3_2 includes additionalOperations?: Record<string, OpenAPIOperation3_2> — but no code path ever writes it, since the language cannot produce such an operation.

So an API that serves, say, a WebDAV surface next to its REST surface can bring the REST half under TypeSpec but must leave the WebDAV half entirely outside the contract, even when targeting openapi-versions: [3.2.0] where the document format can now say it.

Describe the solution you'd like

A way to declare an operation with an arbitrary (registered or vendor) HTTP method, for example:

@method("PROPFIND")
@route("/dav/{path}")
op propfind(@path path: string, @header depth?: string): MultiStatusResponse;

with:

  • the method carried on HttpOperation so third-party emitters can read it (we maintain server emitters built on @typespec/http and would route these to the framework's custom-method registration),
  • @typespec/openapi3 emitting it under additionalOperations when the target version is 3.2.0, and a clear diagnostic (rather than silent omission) when targeting 3.0/3.1 where the field does not exist,
  • query presumably staying first-class per #11171, with this mechanism covering the long tail.

The exact surface (a @method decorator vs widening @route/op declarations) is your call — the ask is that the fact be declarable and emitted.

Describe alternatives you've considered
  • Keeping the non-standard-method surface hand-written outside the spec (what we do today) — works, but splits one service's contract across two sources of truth.
  • Post-processing the emitted document to inject additionalOperations — rejected; it re-creates exactly the document/server divergence spec-first exists to remove.

Happy to contribute the implementation if the design direction is agreed.

主要语言
Java
星标
5.9k
派生
421
平均合并
2 天 3 小时
30 天内合并 PR
176

环境准备

在 Codespaces 中打开

在浏览器里用你自己的 GitHub 账号启动这个项目的开发容器。

  • 没有 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 阅读贡献指南

从这里开始

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

microsoft/typespec 的其他 Issue

查看 microsoft/typespec 的全部 Issue

相似的 Issue

更多 Java Issue

把新 issue 发到你的邮箱

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