Allow the same operationId under different tags

[sianahoret]

Currently oas-validator requires operationId to be globally unique: https://github.com/Mermade/oas-kit/blob/b1bba3fc5007e96a991bf2a015cf0534ac36b88b/packages/oas-validator/index.js#L764.

That prevents you from having the same named method in different controllers, what looks like incorrect.

Particularly (of course, not only possible) the use case is when you implement a few API versions in ProductsControllerV1, ProductsControllerV2 etc. (correspondingly different tags in OAS). That is OK if every such controller has some getProducts method (with exactly the same name).

[MikeRalphson]

The OAS specification says that operationIds have to be unique. It sounds like there is a mismatch between whatever tool you are using and its interpretation of operationId.

[sianahoret]

Is the use case described by me so strange?

I would like to obtain a documentation like follows:

My Service 

  Product  V1
     GET get all products...

  Product  V2
     GET get all products...

I'd like to assign the first entry ProductV1 tag in OAS, the second entry - ProductV2 tag in OAS. And the corresponding controllers to looks like follows:

class ProductsV1Controller {
  getProducts() { ... }
}

class ProductsV2Controller {   <-- the controller already has a different name
  getProducts() { ... }     <-- Why should I use a a different method name here?
}

[sianahoret]

@MikeRalphson, The tool I'm using to correlate the operationId with the controller/method name performs the correlation based on the tag and operationId from OAS.

Current implementation of this lib forces me to use different operationIds (i.e. getProductsV1, getProductsV2) - and there is no way achieve the goal I explained above.

I have to do:

class ProductsV1Controller {
  getProductsV1() { ... }
}

class ProductsV2Controller {   <-- the controller already has a different name
  getProductsV2() { ... }     <-- Why should I use a a different method name here?
}

[sianahoret]

@MikeRalphson Maybe you have a better advise how to achieve my goal?

[MikeRalphson]

Without knowing your tool intimately, all I can comment on is the spec, which says

Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is case-sensitive. Tools and libraries MAY use the operationId to uniquely identify an operation

and the functioning of oas-validator which aims to match up with the spec.

I'm not sure why you want to have the same method names for different versions of your controllers. Presumably the classes don't implement the exact same interface? (But this is your decision/preference, I don't want to get into a debate on it).