feat(openapi-v3): add operationId based on controller/method names

raymondfeng · raymondfeng · commit 89f905b91dae · 2019-03-11T09:01:31.000-07:00
diff --git a/packages/openapi-v3/src/__tests__/integration/controller-spec.integration.ts b/packages/openapi-v3/src/__tests__/integration/controller-spec.integration.ts
@@ -62,7 +62,9 @@ describe('controller spec', () => {
                 },
               },
             },
+            'x-controller-name': 'FooController',
             'x-operation-name': 'create',
+            operationId: 'FooController.create',
           },
         },
       },
diff --git a/packages/openapi-v3/src/__tests__/integration/operation-spec.integration.ts b/packages/openapi-v3/src/__tests__/integration/operation-spec.integration.ts
@@ -5,7 +5,7 @@
 
 import {expect} from '@loopback/testlab';
 import {model, property} from '@loopback/repository';
-import {param, requestBody, getControllerSpec, post} from '../../';
+import {param, requestBody, getControllerSpec, post, get} from '../../';
 
 describe('operation arguments', () => {
   it('generate parameters and requestBody for operation', () => {
@@ -54,7 +54,9 @@ describe('operation arguments', () => {
               },
               'x-parameter-index': 3,
             },
+            'x-controller-name': 'MyController',
             'x-operation-name': 'createUser',
+            operationId: 'MyController.createUser',
           },
         },
       },
@@ -70,4 +72,34 @@ describe('operation arguments', () => {
     const spec = getControllerSpec(MyController);
     expect(spec).to.eql(expectedSpec);
   });
+
+  it('allows operation metadata in @get', () => {
+    class MyController {
+      @get('/users', {
+        operationId: 'find_users',
+        responses: {
+          '200': {description: 'Users found'},
+        },
+      })
+      async findUsers(): Promise<string[]> {
+        return [];
+      }
+    }
+    const expectedSpec = {
+      paths: {
+        '/users': {
+          get: {
+            responses: {
+              '200': {description: 'Users found'},
+            },
+            'x-controller-name': 'MyController',
+            'x-operation-name': 'findUsers',
+            operationId: 'find_users',
+          },
+        },
+      },
+    };
+    const spec = getControllerSpec(MyController);
+    expect(spec).to.eql(expectedSpec);
+  });
 });
diff --git a/packages/openapi-v3/src/__tests__/unit/decorators/operation.decorator.unit.ts b/packages/openapi-v3/src/__tests__/unit/decorators/operation.decorator.unit.ts
@@ -69,7 +69,9 @@ describe('Routing metadata', () => {
       paths: {
         '/greet': {
           get: {
+            'x-controller-name': 'MyController',
             'x-operation-name': 'greet',
+            operationId: 'MyController.greet',
             ...operationSpec,
           },
         },
@@ -93,7 +95,9 @@ describe('Routing metadata', () => {
       paths: {
         '/greeting': {
           post: {
+            'x-controller-name': 'MyController',
             'x-operation-name': 'createGreeting',
+            operationId: 'MyController.createGreeting',
             ...operationSpec,
           },
         },
@@ -117,7 +121,9 @@ describe('Routing metadata', () => {
       paths: {
         '/greeting': {
           put: {
+            'x-controller-name': 'MyController',
             'x-operation-name': 'updateGreeting',
+            operationId: 'MyController.updateGreeting',
             ...operationSpec,
           },
         },
@@ -141,7 +147,9 @@ describe('Routing metadata', () => {
       paths: {
         '/greeting': {
           patch: {
+            'x-controller-name': 'MyController',
             'x-operation-name': 'patchGreeting',
+            operationId: 'MyController.patchGreeting',
             ...operationSpec,
           },
         },
@@ -165,7 +173,9 @@ describe('Routing metadata', () => {
       paths: {
         '/greeting': {
           delete: {
+            'x-controller-name': 'MyController',
             'x-operation-name': 'deleteGreeting',
+            operationId: 'MyController.deleteGreeting',
             ...operationSpec,
           },
         },
@@ -189,7 +199,9 @@ describe('Routing metadata', () => {
       paths: {
         '/greeting': {
           post: {
+            'x-controller-name': 'MyController',
             'x-operation-name': 'createGreeting',
+            operationId: 'MyController.createGreeting',
             ...operationSpec,
           },
         },
@@ -206,7 +218,9 @@ describe('Routing metadata', () => {
     const actualSpec = getControllerSpec(MyController);
 
     expect(actualSpec.paths['/greet']['get']).to.eql({
+      'x-controller-name': 'MyController',
       'x-operation-name': 'greet',
+      operationId: 'MyController.greet',
       responses: {'200': {description: 'Return value of MyController.greet'}},
     });
   });
@@ -220,7 +234,9 @@ describe('Routing metadata', () => {
     const actualSpec = getControllerSpec(MyController);
 
     expect(actualSpec.paths['/greeting']['post']).to.eql({
+      'x-controller-name': 'MyController',
       'x-operation-name': 'createGreeting',
+      operationId: 'MyController.createGreeting',
       responses: {
         '200': {description: 'Return value of MyController.createGreeting'},
       },
@@ -252,13 +268,17 @@ describe('Routing metadata', () => {
       paths: {
         '/parent': {
           get: {
+            'x-controller-name': 'Child',
             'x-operation-name': 'getParentName',
+            operationId: 'Child.getParentName',
             ...operationSpec,
           },
         },
         '/child': {
           get: {
+            'x-controller-name': 'Child',
             'x-operation-name': 'getChildName',
+            operationId: 'Child.getChildName',
             ...operationSpec,
           },
         },
diff --git a/packages/openapi-v3/src/__tests__/unit/decorators/param/param.decorator.unit.ts b/packages/openapi-v3/src/__tests__/unit/decorators/param/param.decorator.unit.ts
@@ -32,6 +32,7 @@ describe('Routing metadata for parameters', () => {
 
       const expectedSpec = anOperationSpec()
         .withOperationName('greet')
+        .withControllerName('MyController')
         .withParameter(paramSpec)
         .withResponse(200, {description: 'Return value of MyController.greet'})
         .build();
@@ -76,6 +77,7 @@ describe('Routing metadata for parameters', () => {
 
       const expectedSpec = anOperationSpec()
         .withOperationName('update')
+        .withControllerName('MyController')
         .withResponse(200, {description: 'Return value of MyController.update'})
         .withParameter({
           name: 'id',
@@ -145,6 +147,7 @@ describe('Routing metadata for parameters', () => {
 
       const expectedSpec = anOperationSpec()
         .withOperationName('greet')
+        .withControllerName('MyController')
         .withResponse(200, {description: 'Return value of MyController.greet'})
         .withParameter({
           name: 'names',
@@ -191,6 +194,7 @@ describe('Routing metadata for parameters', () => {
 
       const expectedSpec = anOperationSpec()
         .withOperationName('greet')
+        .withControllerName('MyController')
         .withResponse(200, {description: 'Return value of MyController.greet'})
         .withParameter({
           name: 'names',
diff --git a/packages/openapi-v3/src/controller-spec.ts b/packages/openapi-v3/src/controller-spec.ts
@@ -186,6 +186,18 @@ function resolveControllerSpec(constructor: Function): ControllerSpec {
     }
 
     operationSpec['x-operation-name'] = op;
+    operationSpec['x-controller-name'] =
+      operationSpec['x-controller-name'] || constructor.name;
+
+    if (operationSpec.operationId == null) {
+      // Build the operationId as `<controllerName>.<operationName>`
+      // Please note API explorer (https://github.com/swagger-api/swagger-js/)
+      // will normalize it as `<controllerName>_<operationName>`
+      operationSpec.operationId =
+        operationSpec['x-controller-name'] +
+        '.' +
+        operationSpec['x-operation-name'];
+    }
 
     if (!spec.paths[path]) {
       spec.paths[path] = {};
diff --git a/packages/rest/src/__tests__/unit/rest.server/rest.server.open-api-spec.unit.ts b/packages/rest/src/__tests__/unit/rest.server/rest.server.open-api-spec.unit.ts
@@ -188,6 +188,7 @@ describe('RestServer.getApiSpec()', () => {
           responses: {'200': {description: ''}},
           'x-controller-name': 'MyController',
           'x-operation-name': 'greet',
+          operationId: 'MyController.greet',
           tags: ['MyTag'],
         },
       },
@@ -248,6 +249,7 @@ describe('RestServer.getApiSpec()', () => {
           },
           'x-controller-name': 'MyController',
           'x-operation-name': 'greet',
+          operationId: 'MyController.greet',
           tags: ['MyController'],
         },
       },
