feat: support the HTTP QUERY method (RFC 10008) - #4007
gentritabazi wants to merge 4 commits into
Conversation
5ab2c5f to
17aba2a
Compare
official-burak
left a comment
official-burak
left a comment
There was a problem hiding this comment.
query is an OpenAPI 3.2 Path Item field. This package still defaults the document to 3.0.0, so the emitted operation is off-spec.
| head?: OperationObject; | ||
| patch?: OperationObject; | ||
| trace?: OperationObject; | ||
| query?: OperationObject; |
There was a problem hiding this comment.
OAS 3.0 and 3.1 Path Item objects have no query field. That lands in 3.2. SwaggerModule still defaults openapi to '3.0.0', so a document with paths['/foos/filtered'].query fails spec validation and Swagger UI drops the operation.
RequestMethod.ALL still expands to get/post/put/delete/patch/options/head/search and never query.
Gate this on OAS 3.2 (or put it under additionalOperations) and include query in the ALL list if Nest actually routes it.
There was a problem hiding this comment.
Both points addressed:
-
Gating on 3.2 the
queryoperation is now stripped from the generated document for anyopenapiversion below3.2.0(newisOas32OrLaterutil +stripQueryOperationsinSwaggerModule.createDocument, which also prunes a path item that becomes empty). So 3.0/3.1 documents stay on-spec and Swagger UI keeps every sibling operation. -
RequestMethod.ALLNest mapsRequestMethod.QUERY -> 'query'in its router method map and@All()binds the adapter's.all()handler, which routes QUERY, so I added'query'to the list the explorer expands for@All()controllers. It is still stripped for pre-3.2 documents by the gate above.
b3ad3a2 to
571b766
Compare
|
Thanks. Gating |
|
This is urgently needed now that NestJS supports query methods with the merge of nestjs/nest#17162. |
The `query` operation is an OpenAPI 3.2 Path Item field, but documents default to 3.0.0, so a `RequestMethod.QUERY` route would emit an off-spec operation. Drop `query` operations when the configured version is below 3.2, mirroring how `webhooks` is gated on 3.1. Sibling operations on the same path are preserved, and the path entry is removed when `query` was its only operation. The strip is applied to the webhook path fold-back too, since that merges after the initial pass.
RequestMethod.ALL maps to the adapter's .all() handler, which routes the HTTP QUERY method (RequestMethod.QUERY -> 'query' in Nest's router method map). Include 'query' in the operations expanded for @ALL() controllers so those routes are represented in the generated document. The operation is still stripped for OpenAPI documents older than 3.2.
571b766 to
43c55f5
Compare
|
@kamilmysliwiec this is ready for review whenever you have a chance. Would love your feedback on whether this is good to merge. |
|
Is there any chance we can get this merged / released ASAP? This seems like a huge add for the NestJS community, and I'd love to start taking advantage of it like 2 months ago. 😁 If there's anything that more supporters can do to help speed this along, let me know. I'll happily devote some cycles! |
7 participants
PR Checklist
Please check if your PR fulfills the following requirements:
PR Type
What kind of change does this PR introduce?
What is the current behavior?
PathItemObjecthas noqueryoperation field, so routes declared with the new HTTP QUERY method (RFC 10008, added toRequestMethodin nestjs/nest#17162) cannot be represented in the generated OpenAPI document.Issue Number: N/A
What is the new behavior?
PathItemObjectaccepts an optionalqueryoperation, so controllers usingRequestMethod.QUERYare exposed under thequerymethod in the generated document — including theirrequestBody(QUERY is defined as a safe method that carries a body).@All()handlers now expand toqueryas well, since Nest mapsRequestMethod.QUERY -> 'query'and routes it through the adapter's.all()handler.Because the
queryPath Item field only exists from OpenAPI 3.2 onwards, it is gated on the document version:SwaggerModule.createDocumentstrips everyqueryoperation (and prunes any path item left empty) whenever theopenapiversion is below3.2.0, keeping 3.0/3.1 documents on-spec. To emit the operation, set the version viaDocumentBuilder#setOpenAPIVersion('3.2.0').Tests cover a
@RequestMapping({ method: RequestMethod.QUERY })route end to end throughSwaggerExplorer(method, path, request body schema, response), the@All()expansion, theisOas32OrLaterutil, and the 3.0/3.1/3.2 stripping behaviour end to end.Does this PR introduce a breaking change?
Other information
RequestMethod.QUERY), which has since shipped in@nestjs/common; the QUERY-specific tests are guarded withdescribe.runIf('QUERY' in RequestMethod)so they run once a compatible@nestjs/commonis installed and skip cleanly otherwise.master(ESM migration +createDocumentrefactor); the stripping is folded into the currentfinalDocumentflow and uses native destructuring (no new runtime dependency).setOpenAPIVersion('3.2.0')requirement once this lands.