support for service.id array: add tests for full coverage, extend and fix type definitions, extend readme

Author: Mairu

README.md

@@ -83,6 +83,8 @@ __Options:__
 ### `service.id`
 
 Defines the name of the id in the swagger path, by default it is `'id'`;
+This can also be an array, if multiple ids are used. For example with feathers-objection or feathers-cassandra.
+For services that extend adapter-commons this is set as parameter in the options when initializing the service.
 
 ### `service.docs`
 
@@ -119,7 +121,7 @@ __Options:__
 - `tags` (*optional*) - Give multiple tags
 - `model` (*optional*) - Override model that is parsed from path
 - `modelName` (*optional*) - Override modelName that is parsed from path
-- `idType` (*optional*) - The swagger type of ids used in paths for this service. value can be an array of types when `service.id` is set to array.
+- `idType` (*optional*) - The swagger type of ids used in paths for this service. Value can be an array of types when `service.id` is set as an array.
 - `idNames` (*optional*) - Object with path parameter names, to customize the idName on operation / method level
   - `get`|`update`|`patch`|`remove` - name of the path parameter for the specific method, use service.id to change it for all
 - `definition`(also `schema` for openapi v3) (*optional*) - Swagger definition of the model of the service, will be merged into global definitions (with all additional generated definitions)

lib/v3/generator.js

@@ -334,7 +334,7 @@ class OpenApiV3Generator extends AbstractApiGenerator {
         };
 
         if (withId) {
-          customDoc.parameters = withId ? idPathParameters(idName, idType, `ID of ${modelName}`) : [];
+          customDoc.parameters = idPathParameters(idName, idType, `ID of ${modelName}`);
         }
 
         if (['post', 'put', 'patch'].includes(httpMethod)) {

test/v2/generator.test.js

@@ -239,6 +239,65 @@ describe('swagger v2 generator', function () {
       expect(specs.paths['/message'].get.responses[200].schema.$ref).to.equal('#/definitions/otherRef');
       expect(specs.paths['/message/{id}'].get.responses[200].schema.$ref).to.equal('#/definitions/getMessage');
     });
+
+    describe('array service.id', function () {
+      it('array service.id should be consumed', function () {
+        const service = memory({ id: ['firstId', 'secondId'] });
+        service.docs = {
+          definition: messageDefinition
+        };
+
+        gen.addService(service, 'message');
+
+        expect(specs.paths['/message/{firstId},{secondId}'].get.parameters[0].type).to.equal('integer');
+        expect(specs.paths['/message/{firstId},{secondId}'].get.parameters[1].type).to.equal('integer');
+      });
+
+      it('array service.id should be consumed with custom idTypes', function () {
+        const service = memory({ id: ['firstId', 'secondId'] });
+        service.docs = {
+          idType: ['string', 'integer'],
+          definition: messageDefinition
+        };
+
+        gen.addService(service, 'message');
+
+        expect(specs.paths['/message/{firstId},{secondId}'].get.parameters[0].type).to.equal('string');
+        expect(specs.paths['/message/{firstId},{secondId}'].get.parameters[1].type).to.equal('integer');
+      });
+
+      it('array service.id should be consumed with custom idNames', function () {
+        const service = memory({ id: ['firstId', 'secondId'] });
+        service.docs = {
+          idType: ['string', 'integer'],
+          idNames: {
+            update: ['otherId', 'additionalId']
+          },
+          definition: messageDefinition
+        };
+
+        gen.addService(service, 'message');
+
+        expect(specs.paths['/message/{firstId},{secondId}'].get.parameters[0].type).to.equal('string');
+        expect(specs.paths['/message/{firstId},{secondId}'].get.parameters[1].type).to.equal('integer');
+        expect(specs.paths['/message/{otherId},{additionalId}'].put.parameters[0].type).to.equal('string');
+        expect(specs.paths['/message/{otherId},{additionalId}'].put.parameters[1].type).to.equal('integer');
+      });
+
+      it('array service.id with custom service.idSeparator should be consumed', function () {
+        const service = memory();
+        service.options.id = ['firstId', 'secondId'];
+        service.options.idSeparator = '|';
+        service.docs = {
+          definition: messageDefinition
+        };
+
+        gen.addService(service, 'message');
+
+        expect(specs.paths['/message/{firstId}|{secondId}'].get.parameters[0].type).to.equal('integer');
+        expect(specs.paths['/message/{firstId}|{secondId}'].get.parameters[1].type).to.equal('integer');
+      });
+    });
   });
 
   // contains only tests that are v2 specific, tests that test "abstract" generator are part of v3 tests
@@ -302,6 +361,18 @@ describe('swagger v2 generator', function () {
         });
     });
 
+    it('should handle :__feathersId in path for service.id as array', function () {
+      addCustomMethod(service, { path: '/:__feathersId/custom' });
+
+      service.id = ['firstId', 'secondId'];
+      service.docs.idType = ['integer', 'string'];
+
+      gen.addService(service, 'message');
+
+      expect(specs.paths['/message/{firstId},{secondId}/custom'].post.parameters[0].type).to.equal('integer');
+      expect(specs.paths['/message/{firstId},{secondId}/custom'].post.parameters[1].type).to.equal('string');
+    });
+
     it('custom path parameters should be handled', function () {
       addCustomMethod(service, { path: '/custom/:myId' });
 

test/v3/generator.test.js

@@ -978,8 +978,7 @@ describe('openopi v3 generator', function () {
       it('array service.id should be consumed', function () {
         const specs = {};
         const gen = new OpenApi3Generator(specs, swaggerOptions);
-        const service = memory();
-        service.options.id = ['firstId', 'secondId'];
+        const service = memory({ id: ['firstId', 'secondId'] });
         service.docs = {
           definition: messageDefinition
         };
@@ -990,20 +989,39 @@ describe('openopi v3 generator', function () {
         expect(specs.paths['/message/{firstId},{secondId}'].get.parameters[1].schema.type).to.equal('integer');
       });
 
-      it('array service.id should be consumed', function () {
+      it('array service.id should be consumed with custom idTypes', function () {
         const specs = {};
         const gen = new OpenApi3Generator(specs, swaggerOptions);
-        const service = memory();
-        service.options.id = ['firstId', 'secondId'];
+        const service = memory({ id: ['firstId', 'secondId'] });
+        service.docs = {
+          idType: ['string', 'integer'],
+          definition: messageDefinition
+        };
+
+        gen.addService(service, 'message');
+
+        expect(specs.paths['/message/{firstId},{secondId}'].get.parameters[0].schema.type).to.equal('string');
+        expect(specs.paths['/message/{firstId},{secondId}'].get.parameters[1].schema.type).to.equal('integer');
+      });
+
+      it('array service.id should be consumed with custom idNames', function () {
+        const specs = {};
+        const gen = new OpenApi3Generator(specs, swaggerOptions);
+        const service = memory({ id: ['firstId', 'secondId'] });
         service.docs = {
           idType: ['string', 'integer'],
+          idNames: {
+            update: ['otherId', 'additionalId']
+          },
           definition: messageDefinition
         };
 
         gen.addService(service, 'message');
 
         expect(specs.paths['/message/{firstId},{secondId}'].get.parameters[0].schema.type).to.equal('string');
         expect(specs.paths['/message/{firstId},{secondId}'].get.parameters[1].schema.type).to.equal('integer');
+        expect(specs.paths['/message/{otherId},{additionalId}'].put.parameters[0].schema.type).to.equal('string');
+        expect(specs.paths['/message/{otherId},{additionalId}'].put.parameters[1].schema.type).to.equal('integer');
       });
 
       it('array service.id with custom service.idSeparator should be consumed', function () {
@@ -1136,6 +1154,18 @@ describe('openopi v3 generator', function () {
         });
     });
 
+    it('should handle :__feathersId in path for service.id as array', function () {
+      addCustomMethod(service, { path: '/:__feathersId/custom' });
+
+      service.id = ['firstId', 'secondId'];
+      service.docs.idType = ['integer', 'string'];
+
+      gen.addService(service, 'message');
+
+      expect(specs.paths['/message/{firstId},{secondId}/custom'].post.parameters[0].schema.type).to.equal('integer');
+      expect(specs.paths['/message/{firstId},{secondId}/custom'].post.parameters[1].schema.type).to.equal('string');
+    });
+
     it('custom path parameters should be handled', function () {
       addCustomMethod(service, { path: '/custom/:myId' });
 

types/index.d.ts

@@ -16,7 +16,7 @@ interface UiIndexFn {
 interface FnGetOperationArgs {
   (options: feathersSwagger.GetOperationArgsOptions): {
     tag?: string,
-    tags?: [string],
+    tags?: string[],
     model?: string,
     modelName?: string,
   } & UnknownObject;
@@ -55,12 +55,12 @@ interface FnSchemasGenerator {
 
 type FnOperationSpecsGeneratorOptions = {
   tag: string,
-  tags: [string],
+  tags: string[],
   model: string,
   modelName: string,
-  idName: string,
-  idType: string,
-  security: [any],
+  idName: string | string[],
+  idType: string | string[],
+  security: any[],
   securities: Securities,
   refs: OperationRefs,
   service: feathersSwagger.SwaggerService<any>,
@@ -161,10 +161,10 @@ declare namespace feathersSwagger {
     modelName?: string;
     idType?: string | string[];
     idNames?: {
-      get?: string;
-      update?: string;
-      patch?: string;
-      remove?: string;
+      get?: string | string[];
+      update?: string | string[];
+      patch?: string | string[];
+      remove?: string | string[];
     };
     securities?: Securities;
     refs?: OperationRefs;
@@ -216,4 +216,6 @@ declare namespace feathersSwagger {
   }): void;
 
   function security(method: string, securities: Securities, security: UnknownObject[]): UnknownObject[];
+
+  function idPathParameters(idName: string | string[], idSeparator: string): string;
 }

types/test.ts

@@ -4,7 +4,7 @@ import swagger, {
   GetOperationArgsOptions,
   operation,
   tag,
-  security,
+  security, idPathParameters,
 } from 'feathers-swagger';
 
 // complete
@@ -255,7 +255,13 @@ const serviceEmptyRefs: ServiceSwaggerAddon = {
 // array idType
 const serviceIdTypeArray: ServiceSwaggerAddon = {
   docs: {
-    idType: ['string'],
+    idType: ['string', 'integer'],
+    idNames: {
+      get: ['firstName', 'secondName'],
+      patch: ['firstName', 'secondName'],
+      remove: ['firstName', 'secondName'],
+      update: ['firstName', 'secondName'],
+    }
   }
 };
 
@@ -296,3 +302,12 @@ security(
 security([], [], [{ any: 'thing' }]);
 // $ExpectError
 security('find', [], ['wrong']);
+
+idPathParameters('id', ',');
+idPathParameters(['first', 'second'], ',');
+// $ExpectError
+idPathParameters(12, ',');
+// $ExpectError
+idPathParameters([12, 13], ',');
+// $ExpectError
+idPathParameters('id', 12);