How is the operationId used from an OpenAPI schema?

Question

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?

Answer 1

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.

Answer 2

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.