operation-id-defined

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

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 without an operationId.

Since 0.12.0, an operationId that is empty or only whitespace is not an issue of this rule but an error of reading the document. apigenie lint prints Operation ID must not be blank with the line and column of the operationId and stops with exit status 2 before any rule runs. Turning the rule off does not change this, and --fix does not fill in the ID.

The OpenAPI linter has a rule of the same name, operation-id-defined, for OpenAPI 3.x documents.

Turn the rule off when no tooling relies on operation IDs.

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

--fix 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).

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.swagger has the details.

commands:
  lint:
    swagger:
      rules:
        operation-id-defined: off

Related rules

Further reading

Last updated on View as Markdown
Was this helpful?