operation-id-defined

Since 0.0.1 · fixed by --fix

This rule checks each operation defined in an OpenAPI schema and warns if operation IDs are missing or empty.

Rule Details

Assigning operation a unique identifier helps with managing them. Identifiers can also be used by code generators to produce implementation of API calls.

The operation-id-defined rule is designed to ensure that each operation in an OpenAPI schema has non-empty operation ID.

Configuration

The optional nonPathNaming value controls generated webhook and component path-item names: scope-prefix (default), path-like, or scope-suffix.

Examples

Good. The following operation has a descriptive name that makes it easy to use the operation properly.

paths:
  /users:
    get:
      operationId: readUserList
      responses:
        "200":
          description: Returns a list of users.

Bad. The following operation does not have a name. It is not entirely clear what it does. Using e.g. cancelReservation would help with it.

paths:
  /reservations:
    delete:
      responses: ...

When Not to Use It

We recommend to always enable this rule.

Automatic fixes

When invoked with --fix, this rule generates deterministic IDs from the HTTP method and location, rendering path placeholders as ByName. Existing IDs are reserved and collisions receive numeric suffixes.

Compatibility

This rule is compatible with all OpenAPI 3.x versions.