Meaning of the term API in the operationId context.

[bachp]

In the context of an operationId. the spec says:

The id [operationId] MUST be unique among all operations described in the API

What is the definition of API in this context?
Does it mean all operations defined in the same file?
All operations used by an application?

Did I just miss the definition or should this be clarified?

[webron]

That's a fair question and needs to be clarified.

The 'basic' limitation would be within the same Swagger description. The real challenge is how it would behave when referencing external files.

[jfiala]

If I understand this correctly, the operationId currently has to be unique for each API endpoint an application provides. If it provides multiple API endpoints, the operationId is only required to be unique per API endpoint.

Currently I use Swagger Springfox/Swagger Codegen to generate code and I get one API class for each controller class (tag). IMHO in fact, it would be totally sufficient to demand that the operationId is unique per RequestMapping path/tag/controller/API class.

What the current interpretation of the specification leads to is that the operationId is suffixed with numbers to guarantee its uniqueness.

Request Paths:
/pet/find
/category/find
/person/find

Generated API definition (provided by Swagger Springfox):
"/pet/find": operationId: findUsingGET
"/category/find": operationId: findUsingGET_1
"/person/find": operationId: findUsingGET_2

The generated code using Swagger Codegen then looks like this:
PetAPI.findUsingGET()
CategoryAPI.findUsingGET_1()
PersonAPI.findUsingGET_2()

So in fact, although IMHO it would be totally sufficient to scope the uniqueness of the operationId per tag/API class, it is now suffixed and generates hardly understandable client code with lots of suffixes.

The current solution to this is to use nicknames for the operations and name them uniquely:
"/pet/find": operationId: pet_findUsingGET
"/category/find": operationId: category_findUsingGET
"/person/find": operationId: person_findUsingGET

This solution is unsatisfying so far that it adds a scoping to methods that are already scoped:
PetAPI.pet_findUsingGET()
CategoryAPI.category_findUsingGET()
PersonAPI.person_findUsingGET()

Wouldn't it be sufficient to demand that the operationId is unique per tag it is associated to (or per Request Path)?

[RobThree]

I wonder what use the OperationId has. I am struggling, as many are, with "Cannot have multiple operations with the same operationId ", and have seen all sorts of solutions like this one to generate OperationId's.

So here's a thought... what if I simply get rid of the OperationId? Or what if I generate an SHA1 hash for the OperationId (based on some context so the Id is 'stable' across builds / versions). What if I simply assign an incrementing number (operation_1, operation_2) etc. for the OperationId? I understand that such Id's might not be as descriptive as GetPetByName OperationId's but, as long as the OperationId is only used by machines and isn't exposed to users by tooling etc, then why not have a SHA1 hash or whatever for an OperationId (as long as I can guarantee it's stable)? And, again, do we even need an OperationId in the first place? AFAIK: "An operationId can be added"; it isn't mandatory, is it?

[MikeRalphson]

what if I simply get rid of the OperationId? It isn't mandatory, is it?

No. And if present, they can be anything you wish, including unique integers, hashes etc. Some tooling, especially code-generation tools may make use of operationIds to generate (say) routing controller names.

[RobThree]

Exactly, that's what I gathered. But I guess my question is: is it used "in the field"? Is there tooling or whatever that's dependent on the OperationId? (Edit: apparently there is; you added another sentence to your post 😉 ) Is it better to provide an OperationId (be it a hash or integer or string like GetPetByName) to better assist tooling or should leaving it out have negligible effects? And should I choose anything other than the, what seems to be commonly used, GetPetByName-like operation ID's, what will the consequences be of having non-descriptive "ID's"?

But so far I'm considering removing OperationID's alltogether from my swagger document.

[MikeRalphson]

Yes, I would personally recommend providing a descriptive operationId if you can, in case your OpenAPI document is ever used for code-generation. The consequence would be less readable generated code / debugging / errors etc.

[handrews]

@MikeRalphson Operation IDs are primarily for use in Link Objects, right?

[MikeRalphson]

I'd not say primarily, as they predate the presence of links in the spec., but that is another use as a shorthand for path + method.

[darrelmiller]

Tooling uses OperationId fairly extensively. Readable OperationIds are generally preferred as it makes it easier to hand edit documents.

[bobvanderlinden]

I personally think the operationId has its use (unique identifier for operations). However, I think it is being misused in many cases.

One tool that is misusing it is the codegen. It uses the operationId for method name and uses the tag(s) for classname. The method names do not need to be unique across all classes for all languages I know of. This becomes especially awkward when the operationId is generated from existing code (like Java) where methods do not need to be unique across all classes. Perfectly reasonable looking Java code is incorrect because methods names are now suddenly unique across classes.

For codegen it would be nice if we could just specify what the classname and methodname should be, separate from the operationId.

For Swagger-UI the operationId is correctly used IMO. It isn't being shown as a kind of 'short name'. It is actually a unique identifier just to reference a specific operation. The operation can be referenced using the # in the URL and (from what I gathered) is used internally to reference JS/HTML elements.

A UUID in this case makes perfect sense and seems more stable than a user-defined Id that needs to look good in order to use it as a method name.

[joanjames-zebra]

Besides codegen and apigee SmartDocs, which tools actually use the operationId?

We started with title case and spaces between words in the operationId for SmartDocs rendering which uses the operationId for titles. Now it seems the spaces may cause trouble in other tools. According to the OpenAPI Spec definition of the operationId ' .. it is RECOMMENDED to follow common programming naming conventions'.

Now I am wondering if we should convert the operationId to Camel Case or hyphenated words? The operationId is being ignored by our current rendering. The summary and description are being used.

What is the best practice for the operationId?

[bobvanderlinden]

What we are doing is create operationIds from classname and method name. For instance something like: UserController.byId. That way it is unique and human-readable. However, when we're passing the specs to a codegen, then we're transforming the specs so that the tag of the operation becomes User and the operationId becomes byId.

This results in general use we have a valid specification. For codegen we have an invalid specification (byId is not unique), but it will at least work for the codegen.

I wouldn't call it 'best practice', but it is how we're coping with this issue.

[handrews]

Fixed by #3823 and #3906