asyncapi 1.0.0 support.

lib/helpers/createSpecification.js

@@ -18,9 +18,16 @@ function createSpecification(definition) {
     'parameters',
     'securityDefinitions',
   ];
-  const v3 = [...v2, 'components'];
+  let v3 = [...v2, 'components'];
 
-  if (specification.openapi) {
+  if (specification.asyncapi) {
+    specification.asyncapi = specification.asyncapi;
+    v3 = [...v3, 'topics', 'baseTopic', 'servers', 'security', 'externalDocs'];
+    v3.forEach(property => {
+      specification[property] = specification[property] || {};
+    });
+    v3.baseTopic = '';
+  } else if (specification.openapi) {
     specification.openapi = specification.openapi;
     v3.forEach(property => {
       specification[property] = specification[property] || {};

lib/helpers/finalizeSpecificationObject.js

@@ -1,4 +1,5 @@
 const parser = require('swagger-parser');
+const { isEmpty } = require('lodash');
 const hasEmptyProperty = require('./hasEmptyProperty');
 
 /**
@@ -26,6 +27,32 @@ function cleanUselessProperties(inputSpec) {
   return improvedSpec;
 }
 
+/**
+ * AsyncAPI specification validator does not accept empty values for a few properties.
+ * Solves validator error: "Schema error should NOT have additional properties"
+ * @function
+ * @param {object} inputSpec - The asyncapi specification
+ * @param {object} improvedSpec - The cleaned version of the inputSpec
+ */
+function cleanUselessPropertiesAsyncApi(inputSpec) {
+  const improvedSpec = JSON.parse(JSON.stringify(inputSpec));
+  const toClean = [
+    'definitions',
+    'responses',
+    'parameters',
+    'securityDefinitions',
+    'paths',
+  ];
+
+  toClean.forEach(unnecessaryProp => {
+    if (hasEmptyProperty(improvedSpec[unnecessaryProp])) {
+      delete improvedSpec[unnecessaryProp];
+    }
+  });
+
+  return improvedSpec;
+}
+
 /**
  * Parse the swagger object and remove useless properties if necessary.
  *
@@ -44,6 +71,12 @@ function finalizeSpecificationObject(swaggerObject) {
   if (specification.openapi) {
     specification = cleanUselessProperties(specification);
   }
+  if (specification.asyncapi) {
+    specification = cleanUselessPropertiesAsyncApi(specification);
+    if (isEmpty(specification.baseTopic)) {
+      delete specification.baseTopic;
+    }
+  }
 
   return specification;
 }

lib/helpers/getSpecificationObject.js

@@ -11,7 +11,6 @@ function getSpecificationObject(options) {
 
   // Parse the documentation containing information about APIs.
   const apiPaths = convertGlobPaths(options.apis);
-
   for (let i = 0; i < apiPaths.length; i += 1) {
     const parsedFile = parseApiFile(apiPaths[i]);
     updateSpecificationObject(parsedFile, specification);

lib/helpers/specification.js

@@ -66,6 +66,8 @@ function getSwaggerSchemaWrongProperties() {
     'scheme',
     'response',
     'parameter',
+    'topic',
+    'server',
   ];
 }
 
@@ -111,21 +113,32 @@ function organizeSwaggerProperties(swaggerObject, pathObject, propertyName) {
     'parameters',
     'definition',
     'definitions',
+    'topic',
+    'topics',
+    'baseTopic',
+    'server',
+    'servers',
+    'security',
+    'externalDocs',
   ];
 
   // Common properties.
   if (simpleProperties.indexOf(propertyName) !== -1) {
     const keyName = correctSwaggerKey(propertyName);
-    const definitionNames = Object.getOwnPropertyNames(
-      pathObject[propertyName]
-    );
-    for (let k = 0; k < definitionNames.length; k += 1) {
-      const definitionName = definitionNames[k];
-      swaggerObject[keyName][definitionName] = Object.assign(
-        {},
-        swaggerObject[keyName][definitionName],
-        pathObject[propertyName][definitionName]
+    if (propertyName === 'baseTopic') {
+      swaggerObject[propertyName] = pathObject[propertyName];
+    } else {
+      const definitionNames = Object.getOwnPropertyNames(
+        pathObject[propertyName]
       );
+      for (let k = 0; k < definitionNames.length; k += 1) {
+        const definitionName = definitionNames[k];
+        swaggerObject[keyName][definitionName] = Object.assign(
+          {},
+          swaggerObject[keyName][definitionName],
+          pathObject[propertyName][definitionName]
+        );
+      }
     }
     // Tags.
   } else if (propertyName === 'tag' || propertyName === 'tags') {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "swagger-jsdoc",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "Generates swagger doc based on JSDoc",
   "main": "index.js",
   "scripts": {
@@ -34,6 +34,7 @@
     "doctrine": "3.0.0",
     "glob": "7.1.4",
     "js-yaml": "3.13.1",
+    "lodash": "4.17.15",
     "swagger-parser": "8.0.0"
   },
   "devDependencies": {

test/asyncapi/v1/README.md

@@ -0,0 +1,3 @@
+# AsyncApi specification tests
+
+Taken from https://www.asyncapi.com/docs/specifications/1.0.0/#A2SObject

test/asyncapi/v1/async-api-with-examples/api.js

@@ -0,0 +1,62 @@
+// Imaginary API helper
+module.exports = function(consumer) {
+  /**
+   * @swagger
+   *
+   * baseTopic: 'command.service.foo'
+   * components:
+   *   schemas:
+   *     QoS:
+   *       type: object
+   *       properties:
+   *         id:
+   *           type: integer
+   *           required: true
+   *           example: 3
+   *   messages:
+   *     ICommand:
+   *       summary: 'send foo command'
+   *       tags:
+   *         - name: 'company'
+   *         - name: 'settings'
+   *       headers:
+   *         type: object
+   *         properties:
+   *           QoS:
+   *             $ref: '#/components/schemas/QoS'
+   *       payload:
+   *         type: object
+   *         properties:
+   *           param:
+   *             type: string
+   *             required: true
+   *             example: FooBarCommandParam
+   *     ICommandResult:
+   *       summary: 'receive foo command result after publish'
+   *       tags:
+   *         - name: 'company'
+   *         - name: 'settings'
+   *       headers:
+   *         type: object
+   *         properties:
+   *           QoS:
+   *             $ref: '#/components/schemas/QoS'
+   *       payload:
+   *         type: object
+   *         properties:
+   *           data:
+   *             type: object
+   *           error:
+   *             type: string
+   *             example: FooBar Not found
+   *
+   * topic:
+   *   foo_result:
+   *     subscribe:
+   *       $ref: '#/components/schemas/ICommandResult'
+   *   foo:
+   *     publish:
+   *       $ref: '#/components/schemas/ICommand'
+   */
+  consumer.subscribe('command.service.foo', () => {});
+};

test/asyncapi/v1/async-api-with-examples/asyncapi.json

@@ -0,0 +1,100 @@
+{
+  "asyncapi": "1.0.0",
+  "info": {
+    "version": "1.0.0",
+    "title": "Sample specification testing async-api-with-examples"
+  },
+  "components": {
+    "schemas": {
+      "QoS": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "integer",
+            "required": true,
+            "example": 3
+          }
+        }
+      }
+    },
+    "messages": {
+      "ICommand": {
+        "summary": "send foo command",
+        "tags": [
+          {
+            "name": "company"
+          },
+          {
+            "name": "settings"
+          }
+        ],
+        "headers": {
+          "type": "object",
+          "properties": {
+            "QoS": {
+              "$ref": "#/components/schemas/QoS"
+            }
+          }
+        },
+        "payload": {
+          "type": "object",
+          "properties": {
+            "param": {
+              "type": "string",
+              "required": true,
+              "example": "FooBarCommandParam"
+            }
+          }
+        }
+      },
+      "ICommandResult": {
+        "summary": "receive foo command result after publish",
+        "tags": [
+          {
+            "name": "company"
+          },
+          {
+            "name": "settings"
+          }
+        ],
+        "headers": {
+          "type": "object",
+          "properties": {
+            "QoS": {
+              "$ref": "#/components/schemas/QoS"
+            }
+          }
+        },
+        "payload": {
+          "type": "object",
+          "properties": {
+            "data": {
+              "type": "object"
+            },
+            "error": {
+              "type": "string",
+              "example": "FooBar Not found"
+            }
+          }
+        }
+      }
+    }
+  },
+  "topics": {
+    "foo_result": {
+      "subscribe": {
+        "$ref": "#/components/schemas/ICommandResult"
+      }
+    },
+    "foo": {
+      "publish": {
+        "$ref": "#/components/schemas/ICommand"
+      }
+    }
+  },
+  "baseTopic": "command.service.foo",
+  "servers": {},
+  "security": {},
+  "externalDocs": {},
+  "tags": []
+}

test/asyncapi/v1/test.js

@@ -0,0 +1,52 @@
+/* global it, before, beforeEach, describe */
+
+const path = require('path');
+const chai = require('chai');
+
+const { expect } = chai;
+const chaiJestSnapshot = require('chai-jest-snapshot');
+
+const swaggerJsdoc = require('../../../lib');
+
+chai.use(chaiJestSnapshot);
+
+before(() => {
+  chaiJestSnapshot.resetSnapshotRegistry();
+});
+
+beforeEach(function() {
+  chaiJestSnapshot.configureUsingMochaContext(this);
+});
+
+const tests = ['async-api-with-examples'];
+
+describe('AsyncApi 1.0.0 examples', () => {
+  tests.forEach(test => {
+    it(`Example: ${test}`, done => {
+      const title = `Sample specification testing ${test}`;
+
+      // eslint-disable-next-line
+      const referenceSpecification = require(path.resolve(
+        `${__dirname}/${test}/asyncapi.json`
+      ));
+
+      const definition = {
+        asyncapi: '1.0.0',
+        info: {
+          version: '1.0.0',
+          title,
+        },
+      };
+
+      const options = {
+        definition,
+        apis: [`${__dirname}/${test}/api.js`],
+      };
+
+      const specification = swaggerJsdoc(options);
+      expect(specification).to.matchSnapshot();
+      expect(specification).to.eql(referenceSpecification);
+      done();
+    });
+  });
+});