REST Lens

Category: Documentation

Description

Every operation in an OpenAPI specification should have an explicit operationId set. The operationId is a unique string used to identify an operation and is fundamental for code generation, documentation, and tooling.

What It Checks

This rule checks each operation in the API specification for the presence of an operationId field. If an operation does not have one explicitly defined, it flags a violation.

Why It Matters

Explicit operation IDs improve:

Code Generation: SDK generators use operationId to name methods (e.g. client.getUsers() instead of client.get_api_v1_users())
Documentation: Tools like Swagger UI use operationId for deep links and anchors
Tooling: API gateways, testing tools, and MCP servers reference operations by ID
Consistency: Naming operations explicitly encourages thoughtful API design

Examples

Good

paths:
  /users:
    get:
      operationId: listUsers
      responses:
        "200":
          description: List of users
    post:
      operationId: createUser
      responses:
        "201":
          description: User created

Bad

paths:
  /users:
    get:
      # Missing operationId
      responses:
        "200":
          description: List of users
    post:
      # Missing operationId
      responses:
        "201":
          description: User created

How to Fix

Add an operationId to every operation. Use a descriptive, camelCase name that reflects the action:

paths:
  /users/{userId}:
    get:
      operationId: getUserById
    put:
      operationId: updateUser
    delete:
      operationId: deleteUser

Configuration

This rule has no configuration options. It is either enabled or disabled.

Related Rules

Rule 3: CRUDy URIs - Avoid CRUD terms in URIs
Rule 75: Consistent Naming - Naming convention enforcement

Operation ID