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