8.4.0: generate every OpenAPI 3.2 operation (QUERY, additionalOperations, HEAD/OPTIONS/TRACE) and stop dropping 3.2 contract parts silently

[joseegman-idoneea]

Summary

The engine accepted openapi: 3.2.0, but running a 3.2 contract for each new feature through it showed parts dropped without a word, or crashing the generator:

3.2 contract	Before	Now
query operation	dropped	generated
additionalOperations (e.g. PURGE)	dropped	generated
head, options, trace (not new in 3.2)	dropped	generated
in: querystring	servers bound it by accident; clients took it and never sent it	form-exploded query object, everywhere
$ref to components/mediaTypes	NullPointerException	resolved
response summary without description	empty description	used as the description
application/json-seq, text/event-stream	a single JSON document with produces = "application/json"	the generation fails, until they are generated

Methods Spring's RequestMethod has no constant for

@RequestMapping only takes RequestMethod's eight methods, so servers map QUERY and the additionalOperations methods with a generated annotation:

@HttpMethodMapping(method = "QUERY", value = "/items", produces = {"application/json"}, consumes = {"application/json"})
default ResponseEntity<List<ItemDTO>> queryItems(@Valid @RequestBody FilterDTO filterDTO) {

The generated HttpMethodMappingConfiguration (Spring MVC or WebFlux variant) registers a RequestMappingHandlerMapping subclass. It builds a RequestMappingInfo with a custom method condition from that annotation, and maps nothing else. It does not replace Spring's mapping (no WebMvcRegistrations), so it cannot clash with an application's own configuration.

The @HttpMethodMapping operations carry no @RequestMapping, so Spring's mapping ignores them. The generated mapping comes first, and a request of another method falls through to Spring's (POST /items is still Spring's 405). For a request of its own method it cannot serve, it answers as Spring would (406/415).

These operations also declare consumes, because Spring checks a @RequestBody's content type only for POST/PUT/PATCH. Without it, a QUERY with a text/plain body got a 400 "body missing" instead of a 415.

It is found by component scanning of the API package, or through @Import(HttpMethodMappingConfiguration.class).

Clients send these methods with HttpMethod.valueOf(...) or @HttpExchange(method = "QUERY"). Spring Framework 5's HttpMethod is an enum, so generating a Spring Boot 2 client fails for them.

Behaviour changes

• Contracts with head/options/trace operations now get those methods generated. They were silently missing before.
• json-seq/SSE contracts now fail the generation. They used to generate code that could not serve the stream. SSE is the next PR.

Known limits (README)

• The generated RestClient class needs an ApiRestClient on a RestClient, or on a RestTemplate with a factory that sends custom methods. The default HttpURLConnection rejects QUERY ("Invalid HTTP method: QUERY", checked).
• springdoc does not list the @HttpMethodMapping operations.
• Spring MVC and Tomcat refuse TRACE by default.

Test plan

• New fixture testOpenApi32. It covers:

  • query with a body;
  • options, head, and PURGE via additionalOperations;
  • in: querystring with a $ref schema;
  • a components/mediaTypes $ref;
  • summary-only responses.

  Generated for the Spring MVC server (Boot 2, Boot 4), WebFlux (Boot 2 getMethodValue(), Boot 3 getMethod().name()), RestClient, WebClient and @HttpExchange.

• Error tests: a Boot 2 client with QUERY; application/json-seq; text/event-stream; a querystring that is not form-encoded

• No existing asset changes

• Engine: 267 tests green, checkstyle green; Maven plugin ITs green; Gradle test integrationTest green (JDK 21)

• Runtime check outside the repo, over real HTTP:

  • servers, 6/6 each on Spring MVC 2.7.18 (configuration imported), WebFlux 2.7.18, WebFlux 3.5.8 and Spring MVC 4.0.8 (configuration found by scanning). The six checks:
    • QUERY with a JSON body filters;
    • PURGE 204;
    • GET still served, POST/DELETE still Spring's 405;
    • QUERY with text/plain gets 415;
    • HEAD and OPTIONS with headers;
    • querystring bound per property.
  • clients on 4.0.8, 4/4: the generated RestClient class on a RestClient, the WebClient class and a blocking @HttpExchange send QUERY, PURGE, HEAD, OPTIONS and the query string. The default RestTemplate fails as documented.
  • the NDJSON runtime suite still passes on 2.7, 3.5 and 4.0.

• README: new "OpenAPI 3.2 operations" section

• Version bumped to 8.4.0 in all 5 places

🤖 Generated with Claude Code

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 43 complexity

Metric	Results
Complexity	43

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}