Conflicting OperationId - Document rename capability

tmack8001 commented 5 years ago

When using the paths.include and paths.exclude functionality to be able to merge a subset of the complete defined API I ran into a fatal error with duplicate operationIds.

Swagger Files (both contain the following operation definition)

"/status/healthcheck": {
  "get": {
    "summary": "healthCheck",
    "operationId": "healthCheckUsingGET",
    "consumes": [
      "application/json"
    ],
    "produces": [
      "application/json;charset=UTF-8"
    ],
    "responses": {
      "200": {
        "description": "OK",
        "schema": {
          "$ref": "#/definitions/Health"
        }
      },
      "404": {
        "description": "Not Found"
      }
   }
}

Error

Error: OperationID conflict: deepCheckUsingGET, healthCheckUsingGET
    at schemas.forEach.schema (~/.nvm/versions/node/v8.1.4/lib/node_modules/swagger-combine/src/SwaggerCombine.js:456:15)
    at Array.forEach (native)
    at SwaggerCombine.combineSchemas (~/.nvm/versions/node/v8.1.4/lib/node_modules/swagger-combine/src/SwaggerCombine.js:412:18)
    at load.then.then.then.then.then.then.then.then.then.then.then (~/.nvm/versions/node/v8.1.4/lib/node_modules/swagger-combine/src/SwaggerCombine.js:30:24)
    at <anonymous>
    at process._tickCallback (internal/process/next_tick.js:169:7)

Proposed Change:

When using paths.exclude to exclude these endpoint operations should allow the filed to be merged even though they have duplicated operationIds.

My combined-config.json has the following defined for both swagger files that contain these operations, but still results in this error.

"paths": {
  "exclude": [
    "/status/deepcheck",
    "/status/healthcheck"
  ]
}

tmack8001 commented 5 years ago

I found a workaround (not documented) that has examples of renaming operationIds. Though it would be nice to not have to do this when the merged routes don't have a conflict in the first place.

Example config that renames the operationIds

{
  "swagger": "2.0",
  "info": {
    "title": "Duplicate OperationID Swagger Combine Example",
    "version": "1.0.0"
  },
  "apis": [
    {
      "url": "./example.1.json",
      "operationIds": {
        "rename": {
          "healthcheck": "service1-healthcheck"
        }
      }
    },
    {
      "url": "./example.2.json"
    }
  ]
}

tmack8001 commented 5 years ago

Upon a second look... actually this isn't an issue at all and swagger-combine is doing the right thing only failing after merge. There are a third definition of this same operationId I didn't initially find.

I'm proposing the above PR to document the ability to rename these operationIds.

maxdome / swagger-combine

Conflicting OperationId - Document rename capability #71