Naming your Operation IDs for better SDK Method Names
What is an Operation ID?
Every Operation Object has
an optional field called
operationId that is globally unique. This field is
required to create SDKs with pleasing method names. The OpenAPI Specification
does not require these IDs by default but Konfig's linter will recommend that
you fill them out.
What is a Tag?
How to name your Operation ID
The best way to name your operation ID:
Prefix your operation IDs with the Tag that is specified in the Operation Object and an underscore character
Authentication_). Konfig will remove the prefix from the operation id and use the suffix for the generated method name. This allows us to make operation ID globally unique while sharing generated method names.note
It is not strictly enforced that you use your tags in your prefix but just make sure your operation IDs are globally unique.
Use camel case (i.e.
createUser). Camel case is succint and since we are already using
_it would be visually confusing to use snake case.
_11paths:_11 /v1/pets/dog: # notice how the path is not used to generate method names_11 post:_11 tags:_11 - Dog # tag is used to determine namespace of method name_11 operationId: Pet_create # does not use the "Dog" tag prefix but still works_11 /v1/pets/cat:_11 post:_11 tags:_11 - Cat_11 operationId: Cat_create
This will generate pleasing SDK class and method names in TypeScript:
_10await dog.create();_10await cat.create();
Both method names are succinct yet not conflicting with each other because they are under different namespaces.