Generated OpenAPI definitions include duplicate operationIds, which violates the OpenAPI spec

Sorting

• I’m submitting a …

  • bug report
  • feature request
  • support request

• I confirm that I

  • used the search to make sure that a similar issue hasn’t already been submit

NOTE: This is almost certainly a dup of the closed issue #183, however since there have been several unanswered requests to re-open that issue, I’m going ahead and filing a new one (since it seems those requests were missed).

Expected Behavior

As required by OpenAPI, I expect tsoa spec to generate paths with operationIds that are unique across the entire API definition. However, if two different controllers have the same method name, tsoa spec will generate the same operationId for both, even though they are two distinct paths. Here’s a trivial example which breaks today:

@Route('one')
class FirstController extends Controller {
    @Get()
    async get(): Promise<void> {}
}

@Route('two')
class SecondController extends Controller {
    @Get()
    async get(): Promise<void> {}
}

Current Behavior

Both of the aforementioned methods are given the same operationId of Get in the generated swagger.json:

...
	"paths": {
		"/one": {
			"get": {
				"operationId": "Get",
...
			}
		},
		"/two": {
			"get": {
				"operationId": "Get",
...
			}
		},
	},
...

This violates the OpenAPI spec, which says the following about operationIds (emphasis added):

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.

Possible Solution

I expect each get() method in the TypeScript source to be given a unique operationId which includes the route or controller name, for example “get_one” or “one_get” or something similar (preferably something that is moderately human-readable).

Steps to Reproduce

As above

Context (Environment)

Version of the library: 3.8.0 Version of NodeJS: 15.14.0

• Confirm you were using yarn not npm: [ ] <-- we use npm exclusively; that’s irrelevant in this case though

Detailed Description

Change the default method of generating operationIds in OpenAPI definitions so that they are unique (and still human-understandable) across the entire generated API definition. This could be accomplished by adding the class name or (preferably) a sanitized form of the route path as a prefix. The operationId should probably conform to standard variable-naming syntax (i.e. avoid special characters like . and -) so it’s easily consumable by code generators for clients.

Another option might be to simply not emit operationIds at all by default, and only emit operationIds for methods with an explicit @OperationId decorator.

Breaking change?

Yes, the proposed change may potentially cause breakage for clients which are doing codegen from OpenAPI definitions generated by Tsoa, since some will rely on the operationId to choose function/method names, and those names would therefore change.

However, this could be avoided by including a backward-compatibility flag in tsoa.json or as an option to tsoa spec. It could also be mitigated manually by adding @OperationIds to all affected methods in application server code.

[joshua-berry-ntnx]

That seems like a good approach to me!

[joshua-berry-ntnx]

Still relevant; not stale