Support the HTTP QUERY method (OpenAPI 3.2 query operation)

[C-luigi]

---

Motivation

The HTTP QUERY method (draft-ietf-httpbis-safe-method-w-body) is a safe, idempotent method that carries a request body — essentially "GET with a body", designed for complex filtering/search requests that don't fit in a URL query string.

OpenAPI 3.2 (released 2025-09-23) added first-class support for it: query is now a valid operation key on a Path Item (alongside get, post, …), plus an additionalOperations map for other/custom HTTP methods.

Server frameworks are starting to expose such endpoints (in our case, FastAPI services declaring QUERY routes, with the OpenAPI document version bumped to 3.2.0 accordingly), and openapi-python-client currently can't generate clients for them.

Current behavior (tested on 0.29.0, same on 0.27.1)

There are two failure modes:

1. A document declaring openapi: 3.2.0 is rejected outright:

Error(s) encountered while generating, client was not created

Failed to parse OpenAPI document

1 validation error for OpenAPI
openapi
  Value error, Only OpenAPI versions 3.1.* are supported, got 3.2.0 [type=value_error, input_value='3.2.0', input_type=str]

2. If the document is downgraded to openapi: 3.1.0 (keeping the query key, which is technically invalid 3.1), generation succeeds — but the query operation is silently skipped. No warning is emitted; the generated client simply has no method for that endpoint, while sibling operations on the same path (e.g. the get) are generated fine.

Minimal spec to reproduce

Running openapi-python-client generate --path repro.json on this document reproduces failure mode 1; changing "openapi" to "3.1.0" reproduces mode 2 (only list_items is generated, list_items_query disappears silently):

{
  "openapi": "3.2.0",
  "info": {"title": "HTTP QUERY method repro", "version": "0.1.0"},
  "paths": {
    "/items": {
      "get": {
        "summary": "List Items",
        "operationId": "list_items",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {"type": "array", "items": {"$ref": "#/components/schemas/Item"}}
              }
            }
          }
        }
      },
      "query": {
        "summary": "List Items with a filter body (HTTP QUERY)",
        "operationId": "list_items_query",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {"schema": {"$ref": "#/components/schemas/ItemFilter"}}
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {"type": "array", "items": {"$ref": "#/components/schemas/Item"}}
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Item": {
        "type": "object",
        "title": "Item",
        "required": ["id", "name"],
        "properties": {
          "id": {"type": "integer", "title": "Id"},
          "name": {"type": "string", "title": "Name"}
        }
      },
      "ItemFilter": {
        "type": "object",
        "title": "ItemFilter",
        "properties": {
          "name": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Name"}
        }
      }
    }
  }
}

Where this lives in the code

As far as I can tell, three places currently pin the supported surface:

• schema/openapi_schema_pydantic/open_api.py — the openapi field validator rejects anything above 3.1.* (failure mode 1).
• schema/openapi_schema_pydantic/path_item.py — PathItem only declares the eight classic operation fields, so a query key is dropped by pydantic.
• parser/openapi.py — EndpointCollection.from_data iterates a hard-coded methods = ["get", "put", "post", "delete", "options", "head", "patch", "trace"] list (failure mode 2).

On the output side there doesn't seem to be any blocker: the generated endpoint modules build kwargs with "method": "get" and call client.get_httpx_client().request(**kwargs), and httpx accepts arbitrary method strings — so "method": "query" should work as-is.

What I'm asking / proposing

Would you be open to supporting the query operation? I'd be happy to contribute the PR — I mainly want to align on scope first. Options, from smallest to largest:

1. Minimal: add query to the PathItem model and the parser's method list, so query operations generate endpoint modules like any other (this alone doesn't help documents that declare 3.2.0).
2. Version acceptance: also relax the version validator to accept 3.2.x (possibly with a warning that only a subset of 3.2 features is understood, similar to how other 3.x features are handled incrementally).
3. Fuller OpenAPI 3.2 support: additionally handle additionalOperations for arbitrary methods — probably a separate, larger effort.

My instinct is that 1 + 2 covers the practical need (FastAPI-style generators emit 3.2.0 documents as soon as one QUERY route exists). I'm aware new features need golden-record fixtures (pdm regen) and a Knope changeset per CONTRIBUTING.md, and I'm fine doing that.

Environment

• OS: Linux (Ubuntu, kernel 6.17)
• Python: 3.14.5
• openapi-python-client: 0.29.0 (also reproduced on 0.27.1)

---

One last note: this isn't a drive-by feature request. I'm available to implement whichever scope you settle on and to see the PR through review. This project has saved me a lot of work, so giving back feels only fair. Just point me in the right direction.