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