Linter rulesSwagger 2.0operation-id-defined

operation-id-defined

Since 0.9.0 · fixed by --fix

This rule checks whether every operation of a Swagger 2.0 document has an operation ID.

Rule Details

The operationId property identifies an operation. Code generators use it to name the methods of generated clients and servers, and documentation tools use it to build links to operations.

The operation-id-defined rule reports Operation ID is not defined for every operation whose operationId is missing or empty.

Configuration

None.

Examples

Good. The operation has an operation ID.

swagger: '2.0'
info:
  title: Reservations
  version: 1.0.0
paths:
  /reservations/{reservationId}:
    delete:
      operationId: cancelReservation
      parameters:
        - name: reservationId
          in: path
          required: true
          type: string
      responses:
        '204':
          description: The reservation was cancelled.

Bad. The operation has no operation ID.

swagger: '2.0'
info:
  title: Reservations
  version: 1.0.0
paths:
  /reservations/{reservationId}:
    delete:
      parameters:
        - name: reservationId
          in: path
          required: true
          type: string
      responses:
        '204':
          description: The reservation was cancelled.

Automatic fixes

When invoked with --fix, this rule sets operationId to an ID generated from the HTTP method and the path. Each literal path segment is appended in PascalCase, and each path parameter is appended as By followed by its name in PascalCase: GET /users/{userId} becomes getUsersByUserId, and GET / becomes getRoot. IDs already used in the document are reserved, and a generated ID that collides with a reserved one gets a numeric suffix starting at 2 (getUsers2).

When Not to Use It

You may disable this rule when no tooling relies on operation IDs.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x documents are linted by the OpenAPI linter, which has a rule of the same name.

Related rules

Further reading