feature: operationId generator v2 compatibility mode (#1283)

* add idFromPathMethod `v2CompatibilityMode`

* add top-level `v2CompatibilityMode` option

* add `v2CompatibilityMode` note to README

* `v2CompatibilityMode` -> `v2OperationIdCompatibilityMode`

MOAR clarity

Author: shockey

README.md

@@ -17,11 +17,11 @@ We'll be consolidating that soon. Just giving you the heads up. You may see refe
 ### Usage
 
 ##### Prerequisites
-- Runtime: 
-  - browser: es5 compatible. IE11+ 
+- Runtime:
+  - browser: es5 compatible. IE11+
   - node v4.x.x
 - Building
-  - node v6.x.x 
+  - node v6.x.x
 
 ##### Download via npm
 
@@ -34,7 +34,7 @@ npm install swagger-client
 ```javascript
 import Swagger from 'swagger-client'
 // Or commonjs
-const Swagger = require('swagger-client') 
+const Swagger = require('swagger-client')
 ```
 
 ##### Import in browser
@@ -134,7 +134,7 @@ const params = {
 
   parameters, // _named_ parameters in an object, eg: { petId: 'abc' }
   securities, // _named_ securities, will only be added to the request, if the spec indicates it. eg: {apiKey: 'abc'}
-  requestContentType, 
+  requestContentType,
   responseContentType,
 
   (http), // You can also override the HTTP client completely
@@ -166,11 +166,11 @@ Swagger('http://petstore.swagger.io/v2/swagger.json')
       client.originalSpec // In case you need it
       client.errors // Any resolver errors
 
-      // Tags interface 
+      // Tags interface
       client.apis.pet.addPet({id: 1, name: "bobby"}).then(...)
 
       // TryItOut Executor, with the `spec` already provided
-      client.execute({operationId: 'addPet', parameters: {id: 1, name: "bobby") }).then(...) 
+      client.execute({operationId: 'addPet', parameters: {id: 1, name: "bobby") }).then(...)
    })
 
 ```
@@ -190,13 +190,24 @@ Swagger({ url: "http://petstore.swagger.io/v2/swagger.json" }).then((client) =>
       .apis
       .pet // tag name == `pet`
       .addPet({ // operationId == `addPet`
-        id: 1, 
+        id: 1,
         body: {
           name: "bobby",
           status: "available"
         }
       })
-      .then(...) 
+      .then(...)
+})
+```
+
+If you'd like to use the operationId formatting logic from Swagger-Client 2.x, set the `v2OperationIdCompatibilityMode` option:
+
+```js
+Swagger({
+  url: "http://petstore.swagger.io/v2/swagger.json",
+  v2OperationIdCompatibilityMode: true
+}).then((client) => {
+  // do things as usual
 })
 ```
 
@@ -221,14 +232,14 @@ Swagger({...}).then((client) => {
           apiPrefix: "v2"
         }
       })
-      .then(...) 
+      .then(...)
 })
 ```
 
-In Browser 
+In Browser
 ----------
 
-Prepare swagger-client.js by `npm run build-bundle` 
+Prepare swagger-client.js by `npm run build-bundle`
 Note, browser version exports class `SwaggerClient` to global namespace
 If you need activate CORS requests, just enable it by `withCredentials` property at `http`
 
@@ -248,7 +259,7 @@ var swaggerClient = new SwaggerClient(specUrl)
          console.error("failed to load the spec" + reason);
       })
       .then(function(addPetResult) {
-         console.log(addPetResult.obj); 
+         console.log(addPetResult.obj);
          // you may return more promises, if necessary
       }, function (reason) {
           console.error("failed on API call " + reason);
@@ -316,7 +327,7 @@ npm run build-bundle # build browser version available at .../browser
 
 # Migration from 2.x
 
-There has been a complete overhaul of the codebase. 
+There has been a complete overhaul of the codebase.
 For notes about how to migrate coming from 2.x,
 please see [Migration from 2.x](docs/MIGRATION_2_X.md)
 

src/helpers.js

@@ -26,20 +26,31 @@ export function isSwagger2(spec) {
 }
 
 // Strategy for determining operationId
-export function opId(operation, pathName, method = '') {
+export function opId(operation, pathName, method = '', {v2OperationIdCompatibilityMode} = {}) {
   if (!operation || typeof operation !== 'object') {
     return null
   }
   const idWithoutWhitespace = (operation.operationId || '').replace(/\s/g, '')
   if (idWithoutWhitespace.length) {
     return escapeString(operation.operationId)
   }
-  return idFromPathMethod(pathName, method)
+  return idFromPathMethod(pathName, method, {v2OperationIdCompatibilityMode})
 }
 
 
 // Create a generated operationId from pathName + method
-export function idFromPathMethod(pathName, method) {
+export function idFromPathMethod(pathName, method, {v2OperationIdCompatibilityMode} = {}) {
+  if (v2OperationIdCompatibilityMode) {
+    let res = `${method.toLowerCase()}_${pathName}`
+      .replace(/[\s!@#$%^&*()_+=[{\]};:<>|./?,\\'""-]/g, '_')
+
+    res = res || `${pathName.substring(1)}_${method}`
+
+    return res
+      .replace(/((_){2,})/g, '_')
+      .replace(/^(_)*/g, '')
+      .replace(/([_])*$/g, '')
+  }
   return `${toLower(method)}${escapeString(pathName)}`
 }
 

src/interfaces.js

@@ -35,7 +35,11 @@ export function makeExecute(swaggerJs = {}) {
 export function makeApisTagOperationsOperationExecute(swaggerJs = {}) {
   // { apis: tag: operations: execute }
   const cb = self.makeExecute(swaggerJs)
-  const tagOperations = self.mapTagOperations({spec: swaggerJs.spec, cb})
+  const tagOperations = self.mapTagOperations({
+    v2OperationIdCompatibilityMode: swaggerJs.v2OperationIdCompatibilityMode,
+    spec: swaggerJs.spec,
+    cb,
+  })
 
   const apis = {}
   for (const tag in tagOperations) {
@@ -54,7 +58,11 @@ export function makeApisTagOperationsOperationExecute(swaggerJs = {}) {
 export function makeApisTagOperation(swaggerJs = {}) {
   const cb = self.makeExecute(swaggerJs)
   return {
-    apis: self.mapTagOperations({spec: swaggerJs.spec, cb})
+    apis: self.mapTagOperations({
+      v2OperationIdCompatibilityMode: swaggerJs.v2OperationIdCompatibilityMode,
+      spec: swaggerJs.spec,
+      cb
+    })
   }
 }
 
@@ -67,7 +75,7 @@ export function makeApisTagOperation(swaggerJs = {}) {
  * `defaultTag` will house all non-tagged operations
  *
  */
-export function mapTagOperations({spec, cb = nullFn, defaultTag = 'default'}) {
+export function mapTagOperations({spec, cb = nullFn, defaultTag = 'default', v2OperationIdCompatibilityMode}) {
   const operationIdCounter = {}
   const tagOperations = {} // Will house all tags + operations
   eachOperation(spec, ({pathName, method, operation}) => {
@@ -78,7 +86,7 @@ export function mapTagOperations({spec, cb = nullFn, defaultTag = 'default'}) {
         return
       }
       const tagObj = tagOperations[tag] = tagOperations[tag] || {}
-      const id = opId(operation, pathName, method)
+      const id = opId(operation, pathName, method, {v2OperationIdCompatibilityMode})
       const cbResult = cb({spec, pathName, method, operation, operationId: id})
 
       if (operationIdCounter[id]) {

test/helpers.js

@@ -12,6 +12,25 @@ describe('helpers', function () {
       // Then
       expect(id).toEqual('get_one')
     })
+    it('should return get_one as an operationId', function () {
+      // When
+      const id = idFromPathMethod('/one', 'get')
+
+      // Then
+      expect(id).toEqual('get_one')
+    })
+    it('should handle strange paths/methods correctly when in v2 mode', function () {
+      const fn = (path, method) => {
+        return idFromPathMethod(path, method, {
+          v2OperationIdCompatibilityMode: true
+        })
+      }
+      // https://github.com/swagger-api/swagger-js/issues/1269#issue-309070070
+      expect(fn('/foo/{bar}/baz', 'get')).toEqual('get_foo_bar_baz')
+
+      expect(fn('/one/{foo}/{bar}', 'get')).toEqual('get_one_foo_bar')
+      expect(fn('/one/{bar}/-----{baz}', 'get')).toEqual('get_one_bar_baz')
+    })
   })
 
   describe('getOperationRaw', function () {

test/index.js

@@ -124,6 +124,35 @@ describe('constructor', () => {
       })
     })
 
+    it('should honor `v2OperationIdCompatibilityMode` when building `apis`', function () {
+      // Given
+      const spec = {
+        swagger: '2.0',
+        paths: {
+          '/foo/{bar}/baz': {
+            get: {
+              description: '',
+              tags: ['myTag']
+            }
+          }
+        }
+      }
+
+      // When
+      return Swagger({
+        spec,
+        v2OperationIdCompatibilityMode: true
+      }).then((swag) => {
+        const {apis} = swag
+
+        // Then
+        expect(apis).toBeAn('object')
+        expect(apis.myTag).toBeAn('object')
+        console.log(apis)
+        expect(apis.myTag.get_foo_bar_baz).toBeA(Function)
+      })
+    })
+
     it('should handle circular $refs when a baseDoc is provided', () => {
       // Given
       const spec = {