Meaning of the term API in the operationId context.

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?

[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)?

[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.