serverless-openapi-documenter 0.0.121 → 0.0.124-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-openapi-documenter",
-  "version": "0.0.121",
+  "version": "0.0.124-beta.1",
   "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config",
   "main": "index.js",
   "keywords": [
@@ -49,12 +49,12 @@
   "license": "MIT",
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^9.1.0",
-    "@redocly/openapi-core": "^1.2.0",
-    "@usebruno/converters": "^0.15.0",
+    "@usebruno/converters": "^0.16.0",
+    "@redocly/openapi-core": "^1.34.5",
     "chalk": "^4.1.2",
     "js-yaml": "^4.1.1",
     "json-schema-for-openapi": "^0.5.0",
-    "openapi-to-postmanv2": "^5.6.0",
+    "openapi-to-postmanv2": "^6.0.0",
     "uuid": "^11.1.0"
   },
   "engines": {

package/src/definitionGenerator.js

@@ -167,11 +167,12 @@ class DefinitionGenerator {
 
     if (documentation.contact) {
       const contactObj = {};
-      contactObj.name = documentation.contact.name || "";
+
+      if (documentation.contact.name) contactObj.name = documentation.contact.name;
 
       if (documentation.contact.url) contactObj.url = documentation.contact.url;
 
-      contactObj.email = documentation.contact.email || "";
+      if (documentation.contact.email) contactObj.email = documentation.contact.email;
 
       const extendedSpec = this.extendSpecification(documentation.contact);
 
@@ -591,7 +592,9 @@ class DefinitionGenerator {
           obj.headers = corsHeaders;
           addHeaders(owaspHeaders);
         } else {
-          obj.headers = owaspHeaders;
+          if (Object.keys(owaspHeaders).length) {
+            obj.headers = owaspHeaders;
+          }
         }
       }
 
@@ -677,10 +680,13 @@ class DefinitionGenerator {
 
   async createRequestBody(requestBodyDetails) {
     const obj = {
-      description: requestBodyDetails.description,
       required: requestBodyDetails.required || false,
     };
 
+    if (requestBodyDetails.description) {
+      obj.description = requestBodyDetails.description;
+    }
+
     obj.content = await this.createMediaTypeObject(
       requestBodyDetails.models
     ).catch((err) => {
@@ -692,7 +698,6 @@ class DefinitionGenerator {
 
   async createMediaTypeObject(models, type) {
     const mediaTypeObj = {};
-
     for (const mediaTypeDocumentation of this.schemaHandler.models) {
       if (models === undefined || models === null) {
         throw new Error(
@@ -700,48 +705,53 @@ class DefinitionGenerator {
         );
       }
 
-      if (Object.values(models).includes(mediaTypeDocumentation.name)) {
-        let contentKey = "";
-        for (const [key, value] of Object.entries(models)) {
-          if (value === mediaTypeDocumentation.name) contentKey = key;
+      for (const modelContentType in models) {
+        let contentKey
+
+        if (models[modelContentType] === mediaTypeDocumentation.name) {
+          contentKey = modelContentType;
         }
-        const obj = {};
 
-        let schema;
-        if (mediaTypeDocumentation?.content) {
-          if (mediaTypeDocumentation.content[contentKey]?.example)
-            obj.example = mediaTypeDocumentation.content[contentKey].example;
+        if (contentKey) {
 
-          if (mediaTypeDocumentation.content[contentKey]?.examples)
-            obj.examples = this.createExamples(
-              mediaTypeDocumentation.content[contentKey].examples
-            );
+          const obj = {};
+          let schema;
+          if (mediaTypeDocumentation.content) {
+            if (mediaTypeDocumentation.content[contentKey]?.example) {
+              obj.example = mediaTypeDocumentation.content[contentKey]?.example;
+            }
 
-          schema = mediaTypeDocumentation.content[contentKey].schema;
-        } else if (
-          mediaTypeDocumentation?.contentType &&
-          mediaTypeDocumentation.schema
-        ) {
-          if (mediaTypeDocumentation?.example)
-            obj.example = mediaTypeDocumentation.example;
+            if (mediaTypeDocumentation.content[contentKey]?.examples) {
+              obj.examples = this.createExamples(
+                mediaTypeDocumentation.content[contentKey].examples
+              );
+            }
 
-          if (mediaTypeDocumentation?.examples)
-            obj.examples = this.createExamples(mediaTypeDocumentation.examples);
+            schema = (mediaTypeDocumentation.schema) ? mediaTypeDocumentation.schema : mediaTypeDocumentation.schemas[contentKey];
+          } else if (mediaTypeDocumentation?.contentType && mediaTypeDocumentation.schema) {
+            if (mediaTypeDocumentation.example) {
+              obj.example = mediaTypeDocumentation.example;
+            }
 
-          schema = mediaTypeDocumentation.schema;
-        }
+            if (mediaTypeDocumentation.examples) {
+              obj.example = mediaTypeDocumentation.examples;
+            }
 
-        const schemaRef = await this.schemaHandler
-          .createSchema(mediaTypeDocumentation.name)
-          .catch((err) => {
-            throw err;
-          });
+            schema = mediaTypeDocumentation.schema;
+          }
 
-        obj.schema = {
-          $ref: schemaRef,
-        };
+          const schemaRef = await this.schemaHandler
+            .createSchema(mediaTypeDocumentation.name)
+            .catch((err) => {
+              throw err;
+            });
 
-        Object.assign(mediaTypeObj, { [contentKey]: obj });
+          obj.schema = {
+            $ref: schemaRef,
+          };
+
+          Object.assign(mediaTypeObj, { [contentKey]: obj });
+        }
       }
     }
 
@@ -861,7 +871,7 @@ class DefinitionGenerator {
         if (
           this.openAPI.components[type][name] &&
           isEqual(schemaObj[name], this.openAPI.components[type][name]) ===
-            false
+          false
         ) {
           delete schemaObj[name];
           newName = `${name}-${uuid()}`;

package/src/schemaHandler.js

@@ -16,6 +16,12 @@ class SchemaHandler {
     this.documentation = serverless.service.custom.documentation;
     this.openAPI = openAPI;
 
+    this.shouldConvert = true;
+    if (/(3\.1\.\d)/g.test(this.openAPI.openapi)) this.shouldConvert = false;
+
+    this.logger.verbose(`OpenAPI version: ${this.openAPI.openapi}`);
+    this.logger.verbose(`Convert Schemas: ${this.shouldConvert}`);
+
     this.modelReferences = {};
 
     this.__standardiseModels();
@@ -42,9 +48,21 @@ class SchemaHandler {
         return model;
       }
 
-      const contentType = Object.keys(model.content)[0];
-      model.contentType = contentType;
-      model.schema = model.content[contentType].schema;
+      if (Object.keys(model.content).length === 1) {
+        const contentType = Object.keys(model.content)[0];
+        model.contentType = contentType;
+        model.contentTypes = [contentType];
+        model.schema = model.content[contentType].schema;
+      } else {
+        model.contentType = null;
+        model.contentTypes = Object.keys(model.content);
+        model.schema = null;
+        model.schemas = {};
+        for (const key in model.content) {
+          Object.assign(model.schemas, { [key]: { schema: model.content[key].schema } });
+        }
+        // model.schema = model.content[contentType].schema;
+      }
 
       return model;
     };
@@ -69,43 +87,52 @@ class SchemaHandler {
   async addModelsToOpenAPI() {
     for (const model of this.models) {
       const modelName = model.name;
-      const modelSchema = model.schema;
+      const schemas = []
+      if (model.schema) {
+        // const modelSchema = model.schema;
+        schemas.push(model.schema)
+      } else {
+        for (const key in model.schemas) {
+          schemas.push(model.schemas[key].schema);
+        }
+      }
 
-      const convertedSchemas = await this.__dereferenceAndConvert(
-        modelSchema,
-        modelName,
-        model
-      ).catch((err) => {
-        if (err instanceof Error) throw err;
-        else return err;
-      });
+      for (const modelSchema of schemas) {
+        const convertedSchemas = await this.__dereferenceAndConvert(
+          modelSchema,
+          modelName,
+          model
+        ).catch((err) => {
+          if (err instanceof Error) throw err;
+          else return err;
+        });
+
+        if (
+          typeof convertedSchemas.schemas === "object" &&
+          !Array.isArray(convertedSchemas.schemas) &&
+          convertedSchemas.schemas !== null
+        ) {
+          for (const [schemaName, schemaValue] of Object.entries(
+            convertedSchemas.schemas
+          )) {
+            if (schemaName === modelName) {
+              this.modelReferences[
+                schemaName
+              ] = `#/components/schemas/${modelName}`;
+            }
 
-      if (
-        typeof convertedSchemas.schemas === "object" &&
-        !Array.isArray(convertedSchemas.schemas) &&
-        convertedSchemas.schemas !== null
-      ) {
-        for (const [schemaName, schemaValue] of Object.entries(
-          convertedSchemas.schemas
-        )) {
-          if (schemaName === modelName) {
-            this.modelReferences[
-              schemaName
-            ] = `#/components/schemas/${modelName}`;
+            this.__addToComponents("schemas", schemaValue, schemaName);
           }
-
-          this.__addToComponents("schemas", schemaValue, schemaName);
+        } else {
+          throw new Error(
+            `There was an error converting the ${model.name
+            } schema. Model received looks like: \n\n${JSON.stringify(
+              model
+            )}.  The convereted schema looks like \n\n${JSON.stringify(
+              convertedSchemas
+            )}`
+          );
         }
-      } else {
-        throw new Error(
-          `There was an error converting the ${
-            model.name
-          } schema. Model received looks like: \n\n${JSON.stringify(
-            model
-          )}.  The convereted schema looks like \n\n${JSON.stringify(
-            convertedSchemas
-          )}`
-        );
       }
     }
   }
@@ -157,18 +184,30 @@ class SchemaHandler {
       }
     );
 
-    this.logger.verbose(
-      `dereferenced model: ${JSON.stringify(dereferencedSchema)}`
-    );
+    if (this.shouldConvert) {
+      this.logger.verbose(
+        `dereferenced model: ${JSON.stringify(dereferencedSchema)}`
+      );
 
-    this.logger.verbose(`converting model: ${name}`);
-    const convertedSchemas = SchemaConvertor.convert(dereferencedSchema, name);
+      this.logger.verbose(`converting model: ${name}`);
+      const convertedSchemas = SchemaConvertor.convert(
+        dereferencedSchema,
+        name
+      );
+
+      this.logger.verbose(
+        `converted schemas: ${JSON.stringify(convertedSchemas)}`
+      );
+      return convertedSchemas;
+    }
 
     this.logger.verbose(
-      `converted schemas: ${JSON.stringify(convertedSchemas)}`
+      `dereferenced model: ${JSON.stringify({
+        schemas: { [name]: dereferencedSchema },
+      })}`
     );
 
-    return convertedSchemas;
+    return { schemas: { [name]: dereferencedSchema } };
   }
 
   async __dereferenceSchema(schema) {
@@ -270,10 +309,8 @@ class SchemaHandler {
   __HTTPError(error, model) {
     if (error.message.includes("HTTP ERROR")) {
       throw new Error(
-        `There was an error dereferencing ${
-          model.name
-        } schema.  \n\n dereferencing message: ${
-          error.message
+        `There was an error dereferencing ${model.name
+        } schema.  \n\n dereferencing message: ${error.message
         } \n\n Model received: ${JSON.stringify(model)}`
       );
     }

package/test.js

@@ -0,0 +1,204 @@
+const $RefParser = require("@apidevtools/json-schema-ref-parser");
+
+const schema = {
+  $id: "http://schemas.aat.org.uk/build/ProgrammeRegistration.json",
+  $schema: "http://json-schema.org/draft-04/schema#",
+  title: "ProgrammeRegistration",
+  description: "Programme registration schema",
+  required: ["programmeRegistrationDetail"],
+  additionalProperties: false,
+  type: "object",
+  properties: {
+    programmeRegistrationDetail: {
+      $ref: "#/definitions/ProgrammeRegistrationType",
+    },
+    programmeRegistrationQuestionResponse: {
+      anyOf: [
+        { type: "null" },
+        {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            questions: {
+              type: "array",
+              items: { $ref: "#/definitions/QuestionResponse" },
+              minItems: 1,
+              maxItems: 30,
+              uniqueItems: true,
+            },
+          },
+        },
+      ],
+    },
+    autoOrderCreate: {
+      anyOf: [{ type: "boolean", default: false }, { type: "null" }],
+    },
+  },
+  version: "1.1.1",
+  definitions: {
+    ProgrammeRegistrationType: {
+      title: "ProgrammeRegistrationType",
+      description: "programme registration type",
+      type: "object",
+      additionalProperties: false,
+      required: [
+        "programmeRegistrationId",
+        "contactId",
+        "trainingProviderOrganisationId",
+        "qualificationId",
+        "startingLevel",
+      ],
+      properties: {
+        programmeRegistrationId: { $ref: "#/definitions/UUID" },
+        programmeRegistrationCRMId: { $ref: "#/definitions/UUID" },
+        contactId: { $ref: "#/definitions/UUID" },
+        trainingProviderOrganisationId: { $ref: "#/definitions/UUID" },
+        qualificationId: { $ref: "#/definitions/UUID" },
+        qualificationLocalCode: {
+          anyOf: [{ type: "null" }, { type: "string" }],
+        },
+        startingLevel: { $ref: "#/definitions/UUID" },
+        expectedEndLevel: {
+          anyOf: [{ $ref: "#/definitions/UUID" }, { type: "null" }],
+        },
+        currentLevel: {
+          anyOf: [{ $ref: "#/definitions/UUID" }, { type: "null" }],
+        },
+        registrationDate: {
+          anyOf: [{ $ref: "#/definitions/AATDate" }, { type: "null" }],
+        },
+        fundingType: {
+          anyOf: [
+            { type: "null" },
+            { $ref: "#/definitions/ProgrammeRegistrationFundingType" },
+          ],
+        },
+        endDate: {
+          anyOf: [{ type: "null" }, { $ref: "#/definitions/AATDate" }],
+        },
+        fundingTypeMembershipFees: {
+          anyOf: [
+            { type: "null" },
+            { $ref: "#/definitions/ProgrammeRegistrationFundingType" },
+          ],
+        },
+        apprenticeship: { type: "boolean", default: false },
+        apprenticeshipStartDate: {
+          anyOf: [{ $ref: "#/definitions/AATDate" }, { type: "null" }],
+        },
+        fullTime: { type: "boolean", default: false },
+        distanceLearning: { type: "boolean", default: false },
+        payingOrganisationId: {
+          anyOf: [{ $ref: "#/definitions/UUID" }, { type: "null" }],
+        },
+        employmentId: {
+          anyOf: [{ $ref: "#/definitions/UUID" }, { type: "null" }],
+        },
+        poNumber: {
+          anyOf: [{ type: "string", maxLength: 50 }, { type: "null" }],
+        },
+        poRequester: {
+          anyOf: [{ type: "string", maxLength: 50 }, { type: "null" }],
+        },
+        assessmentPoNumber: {
+          anyOf: [{ type: "string", maxLength: 50 }, { type: "null" }],
+        },
+        smartEPAId: {
+          anyOf: [{ $ref: "#/definitions/UUID" }, { type: "null" }],
+        },
+        autoOrderCreate: {
+          anyOf: [{ type: "boolean", default: false }, { type: "null" }],
+        },
+        membershipApplicationId: {
+          anyOf: [{ $ref: "#/definitions/UUID" }, { type: "null" }],
+        },
+        gatewayDate: {
+          anyOf: [{ $ref: "#/definitions/AATDate" }, { type: "null" }],
+        },
+        registrationStatus: {
+          anyOf: [{ type: "null" }, { type: "string" }],
+        },
+        registrationStatusDate: {
+          anyOf: [{ $ref: "#/definitions/AATDate" }, { type: "null" }],
+        },
+        givenName: { anyOf: [{ type: "null" }, { type: "string" }] },
+        familyName: { anyOf: [{ type: "null" }, { type: "string" }] },
+        memberId: { anyOf: [{ type: "null" }, { type: "string" }] },
+        birthDate: {
+          anyOf: [{ $ref: "#/definitions/AATDate" }, { type: "null" }],
+        },
+        epaRegisteredOn: {
+          anyOf: [
+            { type: "null" },
+            {
+              type: "boolean",
+              description:
+                "Indicates the user is studying the associated apprenticeship",
+            },
+          ],
+        },
+      },
+    },
+    QuestionResponse: {
+      title: "QuestionResponse",
+      description: "response to a question",
+      type: "object",
+      additionalProperties: false,
+      required: ["questionId", "responseId", "response"],
+      properties: {
+        responseId: { $ref: "#/definitions/UUID" },
+        questionId: { $ref: "#/definitions/UUID" },
+        response: {
+          type: "object",
+          anyOf: [
+            { text: { type: "string" } },
+            { multiLineText: { type: "string" } },
+            { currency: { type: "number" } },
+            { date: { $ref: "#/source/base/AATDate.json" } },
+            { decimal: { type: "number" } },
+            { optionSet: { type: "string" } },
+            { wholeNumber: { type: "integer" } },
+          ],
+        },
+      },
+    },
+    UUID: {
+      title: "UUID",
+      description: "Universally Unique Identifier (all lowercase)",
+      type: "string",
+      pattern: "[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}",
+    },
+    AATDate: {
+      title: "AATDate",
+      description: "AAT Date formatted",
+      type: "string",
+      examples: ["2014-07-17T10:02:21Z"],
+    },
+    ProgrammeRegistrationFundingType: {
+      title: "ProgrammeRegistrationFundingType",
+      description: "funding types for programme registrations",
+      type: "string",
+      enum: [
+        "Employer",
+        "Student",
+        "Training Provider",
+        "AAT(SA)",
+        "AAT NZICA",
+        "Unknown",
+        "Government",
+      ],
+    },
+  },
+};
+
+const main = async () => {
+  let deReferencedSchema = await $RefParser
+    .dereference("schemas.aat.org.uk/build/ProgrammeRegistration.json")
+    .catch((err) => {
+      throw err;
+    });
+
+  console.log(deReferencedSchema);
+};
+
+main().catch((err) => console.error(err));

package/test2.js

@@ -0,0 +1,146 @@
+const $RefParser = require("@apidevtools/json-schema-ref-parser");
+
+const schema = {
+  $id: "http://schemas.aat.org.uk/build/TrainingProviderApprovalDetail.json",
+  $schema: "http://json-schema.org/draft-04/schema#",
+  title: "TrainingProviderApprovalDetail",
+  description: "Training Provider Approval",
+  required: ["approval"],
+  additionalProperties: false,
+  type: "object",
+  properties: {
+    abc: { type: "string" },
+    // approval: { $ref: "#/definitions/TrainingProviderApproval" },
+    // approvalQuestionResponse: {
+    //   anyOf: [
+    //     {
+    //       type: "object",
+    //       properties: {
+    //         questions: {
+    //           type: "array",
+    //           items: { $ref: "#/definitions/QuestionResponse" },
+    //           minItems: 1,
+    //           maxItems: 30,
+    //           uniqueItems: true,
+    //         },
+    //       },
+    //     },
+    //     { type: "null" },
+    //   ],
+    // },
+  },
+  version: "1.1.1",
+  definitions: {
+    // TrainingProviderApproval: {
+    //   title: "TrainingProviderApproval",
+    //   description: "Training Provider Approval",
+    //   required: [
+    //     "TPapprovalId",
+    //     "approvalCRMId",
+    //     "qualificationId",
+    //     "status",
+    //     "qualificationName",
+    //     "organisationId",
+    //   ],
+    //   additionalProperties: false,
+    //   type: "object",
+    //   properties: {
+    //     TPapprovalId: { $ref: "#/definitions/UUID" },
+    //     TPapprovalCRMId: {
+    //       anyOf: [{ $ref: "#/definitions/UUID" }, { type: "null" }],
+    //     },
+    //     approvalCRMId: { $ref: "#/definitions/UUID" },
+    //     organisationId: { $ref: "#/definitions/UUID" },
+    //     qualificationName: { type: "string", maxLength: 100 },
+    //     qualificationShortName: {
+    //       anyOf: [{ type: "string", maxLength: 100 }, { type: "null" }],
+    //     },
+    //     localCode: {
+    //       anyOf: [{ type: "string", maxLength: 20 }, { type: "null" }],
+    //     },
+    //     aatId: { anyOf: [{ type: "number" }, { type: "null" }] },
+    //     qualificationId: { $ref: "#/definitions/UUID" },
+    //     status: {
+    //       type: "string",
+    //       enum: [
+    //         "Sales Prospect",
+    //         "EOI Sent",
+    //         "EOI Received",
+    //         "EOI More Information Requested",
+    //         "EOI Declined",
+    //         "EOI Closed",
+    //         "Application On Hold By TP",
+    //         "Application Pack Sent",
+    //         "Application Pending",
+    //         "Approval Visit Scheduled",
+    //         "Approval Visit Action Plan",
+    //         "Application Closed",
+    //         "Application Withdrawn",
+    //         "Approved",
+    //         "Conditionally Approved",
+    //         "Referred to Conduct & Compliance",
+    //         "Rejected",
+    //         "Inactive",
+    //         "Withdrawn",
+    //       ],
+    //     },
+    //     statusDate: {
+    //       anyOf: [{ $ref: "#/definitions/AATDate" }, { type: "null" }],
+    //     },
+    //     fromDate: {
+    //       anyOf: [{ $ref: "#/definitions/AATDate" }, { type: "null" }],
+    //     },
+    //     untilDate: {
+    //       anyOf: [{ $ref: "#/definitions/AATDate" }, { type: "null" }],
+    //     },
+    //   },
+    // },
+    QuestionResponse: {
+      title: "QuestionResponse",
+      description: "response to a question",
+      type: "object",
+      additionalProperties: false,
+      required: ["questionId", "responseId", "response"],
+      properties: {
+        responseId: { $ref: "#/definitions/UUID" },
+        questionId: { $ref: "#/definitions/UUID" },
+        response: {
+          type: "object",
+          anyOf: [
+            { text: { type: "string" } },
+            { multiLineText: { type: "string" } },
+            { currency: { type: "number" } },
+            { date: { $ref: "#/source/base/AATDate.json" } },
+            { decimal: { type: "number" } },
+            { optionSet: { type: "string" } },
+            { wholeNumber: { type: "integer" } },
+          ],
+        },
+      },
+    },
+    UUID: {
+      title: "UUID",
+      description: "Universally Unique Identifier (all lowercase)",
+      type: "string",
+      pattern: "[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}",
+    },
+    AATDate: {
+      title: "AATDate",
+      description: "AAT Date formatted",
+      type: "string",
+      examples: ["2014-07-17T10:02:21Z"],
+    },
+  },
+};
+
+const schema2 = { type: "object", properties: { a: { type: "string" } } };
+
+const main = async () => {
+  const bundledSchema = await $RefParser.bundle(schema).catch((err) => {
+    throw err;
+  });
+
+  console.log(bundledSchema);
+};
+
+main().catch((err) => console.error(err));