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

Aperta
  • Qualcosa non va?
#11,668 2 commenti 1 reazione 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Funzionalità
Chiarezza
Da chiarire
Stato di attività
Tranquilla
Stack tecnologico
openapi
Ambito
api, backend-api-design

Direzione di ricerca

Inizia dal modello HttpVerb e HttpOperation di @typespec/http, quindi segui OpenAPIPathItem3_2 di @typespec/openapi3 e l’emissione degli elementi path. Verifica come vengono selezionate le versioni di destinazione e come vengono segnalate le diagnosi. Il lavoro è completato quando i metodi personalizzati possono essere dichiarati, sono esposti agli emitter, vengono emessi come additionalOperations per OpenAPI 3.2 e viene generata una diagnosi per le destinazioni non supportate.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.

Lingua principale
Java
Stelle
5.9k
Fork
421
Merge medio
2g 3h
PR unite (30g)
176

Preparare l'ambiente

Apri in Codespaces

Avvia il container di sviluppo del progetto nel browser, con il tuo account GitHub.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di microsoft/typespec

Tutte le issue di microsoft/typespec

Issue simili

Altre issue su Java

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.