How to fix an unsupported HTTP method in OpenAPI

An OpenAPI Path Item can contain standard operation fields such as get, post, and patch. It cannot use an application action such as fetch as the HTTP method field.

Broken YAML

This document puts a nonstandard fetch field under /users:

openapi: 3.1.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users:
    fetch:
      operationId: fetchUsers
      responses:
        '200':
          description: Users returned

Why it fails

fetch is a JavaScript API name and an action word. It is not an HTTP request method that the OpenAPI Path Item Object defines. Redocly therefore reports Property fetch is not expected here at #/paths/~1users/fetch.

Use the real wire method as the field name. Put a stable action name in operationId if generated SDKs should expose a method such as listUsers or fetchUsers.

Corrected YAML

Use get for a read operation and keep the action name in operationId:

openapi: 3.1.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users:
    get:
      operationId: listUsers
      responses:
        '200':
          description: Users returned

OpenAPI 3.0 vs 3.1

OpenAPI 3.0 and OpenAPI 3.1 define the same operation fields: get, put, post, delete, options, head, patch, and trace. Use lowercase field names.

Custom metadata is permitted only as a specification extension with an x- prefix. An extension such as x-action-name: fetchUsers can add metadata, but it does not define an HTTP operation.

Specification sections: OpenAPI 3.0.4 and OpenAPI 3.1.1.

Validate the fix

Save the complete document as openapi.yaml, then run:

pnpm --package=@redocly/cli@2.53.3 dlx redocly lint openapi.yaml --extends=minimal

The corrected document removes the structural Property fetch is not expected here error. Review any remaining preset warnings separately.