OpenAPI Best Practices

general > operation-operationId

Guidance

This operation ID is a reference for the operation that can be used to visually suggest a connection

to other operations. It's also used for the URL in some documentation systems.

Make the value lower-hyphen-case and use a name for the action that does not relate to the HTTP

message but instead the actual action being performed. For example, create-polygon, search-by-polygon, or filter-companies.

Message

Operation '{{apiContract.method}}' must have and operationId field describing the actions that are being performed in hyphen-case.

Examples

valid

paths:
  /events:
    get:
      operationId: get-events
      summary: Get a list of events
      description: Returns a list of events that match the specified criteria
      responses:
        '200':
          description: OK

invalid

paths:
  /events:
    get:
      summary: Get a list of events
      description: Returns a list of events that match the specified criteria
      responses:
        '200':
          description: OK

Applies to Operation

Constraint

Type: Declarative Validation