Duplicate operationId's for routes supporting multiple versions

[Deon Groenewald]

Is there an existing issue for this?

• I have searched the existing issues

Current behavior

Routes that support multiple versions, either by specifying the versions on the controller or the routes themselves, result in duplicate operationId's in the same specification.

Breaking the requirement for operationId's to be unique amongst all operations causes some tools, like code generation, to fail.

The SwaggerModule.createDocument() function does support passing in an operationIdFactory function to customise the generated operationId's and I was hoping it would offer a simple option to workaround the problem.

However, the function is called multiple times with the same controllerKey and methodKey and isn't really provided with enough information about the route/version so would have to do some additional book-keeping of its own to try an generate a unique ID each time which isn't ideal.

Minimum reproduction code

https://github.com/deongroenewald/nestjs-multiversion-duplicate-operation-id

Steps to reproduce

1. npm start
2. Navigate to the specification: http://localhost:3000/api-json
3. Note that there are two routes with the same operationId: AppController_getHello

{
  "openapi": "3.0.0",
  "paths": {
    "/v1": {
      "get": {
        "operationId": "AppController_getHello",
        "parameters": [],
        "responses": {
          "200": {
            "description": ""
          }
        }
      }
    },
    "/v2": {
      "get": {
        "operationId": "AppController_getHello",
        "parameters": [],
        "responses": {
          "200": {
            "description": ""
          }
        }
      }
    }
  },
  "info": {
    "title": "Cats example",
    "description": "The cats API description",
    "version": "1.0",
    "contact": {}
  },
  "tags": [{
    "name": "cats",
    "description": ""
  }],
  "servers": [],
  "components": {
    "schemas": {}
  }
}

Expected behavior

The OpenAPI specification states that the operationId MUST be unique among all operations:

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, therefore, it is RECOMMENDED to follow common programming naming conventions.

• Automatically generated operationIds should be guaranteed to be unique
• operationIdFactory methods should be provided with enough information to distinguish between what version of the route the operationId is being generated for.

Package version

7.1.2

NestJS version

10.0.0

Node.js version

v18.14.1

In which operating systems have you tested?

• macOS
• Windows
• Linux

Other

No response

[Kamil Mysliwiec]

Ref #1949