[tmeghe]

Description

RFC 10008 standardises the HTTP QUERY method: a safe, idempotent request that carries its query in the request body. OpenAPI 3.2 adds query as a fixed field of the Path Item Object.

Today a query operation gets no page. Since #1440, path items are filtered through an HTTP method list that has no query. Even before #1440, it had no code samples (openapi-to-postmanv2 < 6.4.0 ignores query) and no badge colour (badge--undefined).

Changes

• plugin:
  • create pages for query operations, for OpenAPI 3.2 and later only. query is a Path Item field only from 3.2, so older specs skip it like any unknown key;
  • share one HTTP method list (HTTP_METHODS in src/openapi/httpMethods.ts), now with query. The page filter, the Postman servers cleanup, the callback tabs and isOperationName all use it, so isOperationName also gains trace;
  • add query to the Path Item types.
• plugin: require openapi-to-postmanv2 ^6.4.0, the first version that builds a QUERY request (only for openapi: 3.2.x specs). The lock keeps the 6.4.2 from chore(deps): bump openapi-to-postmanv2 from 6.3.3 to 6.4.2 #1701.
• theme: the QUERY badge uses the GET colour (badge--primary). Like GET, it is a safe and idempotent read, and the six Infima badge colours are all taken.
• demo:
  • add a "Search Cakes" query operation to the OpenAPI 3.2 bakery example;
  • add the query sidebar label to the demo styles, to the palette themes (src/css/themes and the served copies in static/themes, using GET colours), and to the styling docs snippets.
• template: add the query sidebar label to the create-docusaurus-openapi-docs template, with the GET colour.

Tests

• openapi.test.ts:
  • an OpenAPI 3.2 spec gives a QUERY page bound to a QUERY Postman request, next to a GET on the same path;
  • an OpenAPI 3.1 spec skips the query operation and keeps the GET.
• createCallbacks.test.ts (new): the QUERY callback tab.
• utils/utils/openapi.test.ts (new): isOperationName accepts query, trace and $ref.
• MethodEndpoint/index.test.ts (new): the QUERY badge colour.

Each new test fails on main, except the 3.1 case, which main already skips. On Node 24, yarn test passes 661/661 and yarn build-packages passes. Prettier and eslint report nothing new on the touched files.

Checked in the demo:

• the badge and the sidebar label;
• the curl sample (curl -L -X QUERY '…/cakes/search' -H 'Content-Type: application/json' -d '{…}');
• "Send API Request" sends QUERY, tested with a temporary servers entry.

Note: some local checks already fail on main and are not touched here:

• yarn lint crashes on cypress/.eslintrc.js: env cypress/globals is unknown with eslint-plugin-cypress 7;
• eslint reports react-hooks/rules-of-hooks in MethodEndpoint/index.tsx;
• yarn format flags files that are already unformatted, including utils/types.ts and utils/types/open-api.ts, which get a one-line type here.

🤖 Generated with Claude Code

[sserrata]

Thanks for adding QUERY support. One bug must be fixed before merge, and a few smaller items are listed below.

Other items (outside the diff):

• packages/create-docusaurus-openapi-docs/templates/default/src/css/custom.css: The project template has no .query sidebar badge rule, so new sites show QUERY operations with no method label. Please add the same rule as in the demo.

[sserrata]

Bug: query is now handled for every spec version, but openapi-to-postmanv2 builds a request only for OpenAPI 3.2. For a 3.0 or 3.1 spec with paths./x.query, the page has api.postman undefined. The explorer then uses new sdk.Request(undefined), which defaults to GET, so Send calls fetch with GET and a body and the browser rejects it. The snippets also show GET. The test 'creates a page without a request for query operations before OpenAPI 3.2' accepts this state. Please include query only for openapi >= 3.2, or build a fallback request from the method and path when the converter returns none.

[tmeghe]

Good catch, thanks! I went with your first option: query now only makes a page for OpenAPI 3.2+, so older specs skip it like any unknown key. The 3.1 test checks that now (feba142).

[sserrata]

The HTTP method list is copied in four places: this servers cleanup, HTTP_METHODS, the callbacks Map in createCallbacks.ts, and operationNames in src/openapi/utils/utils/openapi.ts. operationNames still has no query, so isOperationName("query") is false. Please export one method list and use it in all four places.

[tmeghe]

Done in cb2eba7: one HTTP_METHODS list in src/openapi/httpMethods.ts, used in all four places. I kept it alphabetical so the callback tabs keep their order, and isOperationName now knows trace and query too.

[sserrata]

This now conflicts with main: #1701 already moved openapi-to-postmanv2 to 6.4.2. Please merge main and run yarn install so that the lock entry matches the new ^6.4.0 range.

[tmeghe]

Merged main in cab2543. The entry is now openapi-to-postmanv2@^6.4.0, at the same 6.4.2 as #1701, and yarn install leaves it as is.

[sserrata]

Not blocking: the same .query rules are copied into 14 theme files (7 in demo/src/css/themes, 7 in demo/static/themes). If a shared GET/QUERY rule is possible, it would be easier to maintain.

[tmeghe]

I had a look, but each palette hard-codes its colours per selector (no variables), so sharing them would mean reworking all seven palettes. For now each rule is a single GET/QUERY selector list. Happy to do that refactor in a follow-up.

[tmeghe]

Thanks for the review! I also added the .query sidebar label to the create-docusaurus-openapi-docs template in ef10ad5, with the GET colour like the badge.