13

In an OpenAPI schema, it includes the optional element operationId.

How is this used and why is it optional? Well, at least with the .NET Core library "Swashbuckle" they say it's optional.

My guess is that it is linked to how an SDK is consumed. For example, I can make a Typescript SDK from any valid OpenAPI schema... so I'm guessing it's somehow linked to how that Typescript SDK is generated and then consumed/used?

Adil Hussain
  • 30,049
  • 21
  • 112
  • 147
Pure.Krome
  • 84,693
  • 113
  • 396
  • 647
  • There is a request to make the `OperationId` mandatory: https://github.com/OAI/OpenAPI-Specification/issues/1907 ... I think this question might get a better audience right there – Helder Sepulveda Mar 15 '20 at 14:06

2 Answers2

10

Yes, one of the primary uses for operationId is as a basis for the method name in a generated SDK. But this is not the only use. It might also be used, e.g., as an anchor in generated documentation. It could be used anywhere a unique identifier for the operation is needed.

Mike Kistler
  • 437
  • 2
  • 10
  • 1
    Ah! so it is used in the SDK, then! But, what happens if none is provided? What does the SDK generate for a method to call the endpoint? – Pure.Krome Mar 16 '20 at 23:17
  • 2
    Some tools will make one up -- maybe based on the path and HTTP method. Our SDK generator actually throws an error -- it requires an operationId to be specified -- primarily to avoid really ugly method names. – Mike Kistler Mar 18 '20 at 02:47
10

The operationId section of the Paths and Operators page in the OpenAPI Guide describes this property as:

operationId is an optional unique string used to identify an operation. If provided, these IDs must be unique among all operations described in your API.

...

Some common use cases for operationId are:

  • Some code generators use this value to name the corresponding methods in code.
  • Links can refer to the linked operations by operationId.
Adil Hussain
  • 30,049
  • 21
  • 112
  • 147