operation-id-defined

Since 0.0.1 · fixed by --fix · In the rulesets: Recommended at error, Strict at error, All at error

This rule checks that every operation has a non-empty operationId: those of paths, webhooks and the path items under components, and those of callbacks.

Rule details

The operation ID is the name of the operation everywhere outside the document: the function a generated client exposes, the handler a generated server asks you to implement, the anchor of the documentation, the key of a mock scenario. An operation without one gets a name made up by each tool, and the names differ.

The rule reports Operation ID is not defined. An operation that several paths, webhooks, callbacks or components share through a $ref is one operation: it is reported once, and --fix names it after the first path that uses it, else the first webhook, else the first callback, else the component.

Configuration

An object with one optional property, nonPathNaming, which decides how --fix names the operations of webhooks, of callbacks and of the path items under components: scope-prefix (the default, Webhook/...), path-like (as for a path) or scope-suffix (.../Webhook). A callback operation is named after its callback, not after the runtime expression of its URL: the post of a callback onEvent becomes postCallbackOnEvent, postOnEvent or postOnEventCallback. Two callbacks of the same name, of different operations, are told apart by the numeric suffix below.

Examples

Good. The name says what the operation does.

paths:
  /users:
    get:
      operationId: listUsers
      responses:
        "200":
          description: A page of users.

Bad. No name; a client would call it delete and the path.

paths:
  /reservations/{id}:
    delete:
      responses:
        "204":
          description: The reservation is cancelled.

Automatic fixes

--fix writes an ID made of the method and the path, with each placeholder as By and its name: GET /users/{id} becomes getUsersById. IDs already in the document are kept, and a generated ID that would repeat one gets a numeric suffix.

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.rules has the details.

commands:
  lint:
    rules:
      operation-id-defined: off
Was this helpful?