feat: support x-webhooks (#235)

* Rename example folder

* support x-webhooks

.npmignore

@@ -7,7 +7,7 @@
 .nvm
 .eslintrc.js
 external.jsdoc
-example/
+examples/
 docs/
 jsdoc/
 test/

docs/README.md

@@ -4,7 +4,7 @@ Quick-start:
 
 - [Getting started](./GETTING-STARTED.md)
 - [CLI](./CLI.md)
-- [Examples](../example)
+- [Examples](../examples)
 
 Before you submit an issue:
 

example/app/app.js → examples/app/app.js

@@ -40,7 +40,7 @@ const options = {
   swaggerDefinition,
   // Path to the API docs
   // Note that this path is relative to the current directory from which the Node.js is ran, not the application itself.
-  apis: ['./example/app/routes*.js', './example/app/parameters.yaml'],
+  apis: ['./examples/app/routes*.js', './examples/app/parameters.yaml'],
 };
 
 // Initialize swagger-jsdoc -> returns validated swagger spec in json format

examples/extensions/example.js

@@ -0,0 +1,23 @@
+/* istanbul ignore file */
+
+/**
+ * Example taken from https://redocly.github.io/redoc/openapi.yaml
+ *
+ * @swagger
+ * x-webhooks:
+ *  newPet:
+ *    post:
+ *      summary: New pet
+ *      description: Information about a new pet in the systems
+ *      operationId: newPet
+ *      tags:
+ *        - pet
+ *      requestBody:
+ *        content:
+ *          application/json:
+ *            schema:
+ *              $ref: "#/components/schemas/Pet"
+ *      responses:
+ *        "200":
+ *          description: Return a 200 status to indicate that the data was received successfully
+ */

examples/extensions/extensions.spec.js

@@ -0,0 +1,17 @@
+const swaggerJsdoc = require('../..');
+const referenceSpecification = require('./reference-specification.json');
+
+describe('Example for using extensions', () => {
+  it('should support x-webhooks', () => {
+    const result = swaggerJsdoc({
+      swaggerDefinition: {
+        info: {
+          title: 'Example with extensions',
+          version: '0.0.1',
+        },
+      },
+      apis: ['./examples/extensions/example.js'],
+    });
+    expect(result).toEqual(referenceSpecification);
+  });
+});

examples/extensions/reference-specification.json

@@ -0,0 +1,32 @@
+{
+  "info": { "title": "Example with extensions", "version": "0.0.1" },
+  "swagger": "2.0",
+  "paths": {},
+  "definitions": {},
+  "responses": {},
+  "parameters": {},
+  "securityDefinitions": {},
+  "tags": [],
+  "x-webhooks": {
+    "newPet": {
+      "post": {
+        "summary": "New pet",
+        "description": "Information about a new pet in the systems",
+        "operationId": "newPet",
+        "tags": ["pet"],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/Pet" }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Return a 200 status to indicate that the data was received successfully"
+          }
+        }
+      }
+    }
+  }
+}

example/yaml-anchors-aliases/yaml-anchors-aliases.spec.js → examples/yaml-anchors-aliases/yaml-anchors-aliases.spec.js

@@ -11,8 +11,8 @@ describe('Example for using anchors and aliases in YAML documents', () => {
         },
       },
       apis: [
-        './example/yaml-anchors-aliases/x-amazon-apigateway-integrations.yaml',
-        './example/yaml-anchors-aliases/example.js',
+        './examples/yaml-anchors-aliases/x-amazon-apigateway-integrations.yaml',
+        './examples/yaml-anchors-aliases/example.js',
       ],
     });
     expect(result).toEqual(referenceSpecification);

package.json

@@ -6,7 +6,7 @@
     "node": ">=12.0.0"
   },
   "scripts": {
-    "start": "node example/app/app.js",
+    "start": "node examples/app/app.js",
     "lint": "eslint .",
     "test:lint": "eslint .",
     "test:js": "jest --verbose",

src/specification.js

@@ -104,7 +104,16 @@ function finalize(swaggerObject) {
  * @param {string} property
  */
 function organize(swaggerObject, annotation, property) {
-  if (property.startsWith('x-')) return; // extensions defined "inline" in annotations are not useful for the end specification
+  // Root property on purpose.
+  // @see https://github.com/OAI/OpenAPI-Specification/blob/master/proposals/002_Webhooks.md#proposed-solution
+  if (property === 'x-webhooks') {
+    swaggerObject[property] = annotation[property];
+  }
+
+  // Other extensions can be in varying places depending on different vendors and opinions.
+  // The following return makes it so that they are not put in `paths` in the last case.
+  // New specific extensions will need to be handled on case-by-case if to be included in `paths`.
+  if (property.startsWith('x-')) return;
 
   const commonProperties = [
     'components',

test/cli.spec.js

@@ -33,13 +33,13 @@ describe('CLI module', () => {
   });
 
   it('should require arguments with jsDoc data about an API', async () => {
-    const result = await sh(`${bin} -d example/app/swaggerDefinition.js`);
+    const result = await sh(`${bin} -d examples/app/swaggerDefinition.js`);
     expect(result.stdout).toMatchSnapshot();
   });
 
   it('should create swagger.json by default when the API input is good', async () => {
     const result = await sh(
-      `${bin} -d example/app/swaggerDefinition.js example/app/routes.js`
+      `${bin} -d examples/app/swaggerDefinition.js examples/app/routes.js`
     );
     expect(result.stdout).toBe('Swagger specification is ready.\n');
     const specification = fs.statSync('swagger.json');
@@ -48,7 +48,7 @@ describe('CLI module', () => {
 
   it('should create swagger.json by default when the API input is from definition file', async () => {
     const result = await sh(
-      `${bin} -d test/files/v2/api_definition.js example/app/routes.js`
+      `${bin} -d test/files/v2/api_definition.js examples/app/routes.js`
     );
     expect(result.stdout).toBe('Swagger specification is ready.\n');
     const specification = fs.statSync('swagger.json');
@@ -57,7 +57,7 @@ describe('CLI module', () => {
 
   it('should accept custom configuration for output specification', async () => {
     const result = await sh(
-      `${bin} -d example/app/swaggerDefinition.js -o customSpec.json example/app/routes.js`
+      `${bin} -d examples/app/swaggerDefinition.js -o customSpec.json examples/app/routes.js`
     );
     expect(result.stdout).toBe('Swagger specification is ready.\n');
     const specification = fs.statSync('customSpec.json');
@@ -66,7 +66,7 @@ describe('CLI module', () => {
 
   it('should create a YAML swagger spec when a custom output configuration with a .yaml extension is used', async () => {
     const result = await sh(
-      `${bin} -d example/app/swaggerDefinition.js -o customSpec.yaml example/app/routes.js`
+      `${bin} -d examples/app/swaggerDefinition.js -o customSpec.yaml examples/app/routes.js`
     );
     expect(result.stdout).toBe('Swagger specification is ready.\n');
     const specification = fs.statSync('customSpec.yaml');
@@ -75,7 +75,7 @@ describe('CLI module', () => {
 
   it('should allow a JavaScript definition file', async () => {
     const result = await sh(
-      `${bin} -d test/files/v2/api_definition.js example/app/routes.js`
+      `${bin} -d test/files/v2/api_definition.js examples/app/routes.js`
     );
     expect(result.stdout).toBe('Swagger specification is ready.\n');
     const specification = fs.statSync('swagger.json');
@@ -84,7 +84,7 @@ describe('CLI module', () => {
 
   it('should allow a JSON definition file', async () => {
     const result = await sh(
-      `${bin} -d test/files/v2/api_definition.json example/app/routes.js`
+      `${bin} -d test/files/v2/api_definition.json examples/app/routes.js`
     );
     expect(result.stdout).toBe('Swagger specification is ready.\n');
     const specification = fs.statSync('swagger.json');
@@ -93,7 +93,7 @@ describe('CLI module', () => {
 
   it('should allow a YAML definition file', async () => {
     const result = await sh(
-      `${bin} -d test/files/v2/api_definition.yaml example/app/routes.js`
+      `${bin} -d test/files/v2/api_definition.yaml examples/app/routes.js`
     );
     expect(result.stdout).toBe('Swagger specification is ready.\n');
     const specification = fs.statSync('swagger.json');
@@ -112,7 +112,7 @@ describe('CLI module', () => {
 
   it('should report YAML documents with errors', async () => {
     const result = await sh(
-      `${bin} -d example/app/swaggerDefinition.js test/files/v2/wrong-yaml-identation.js`
+      `${bin} -d examples/app/swaggerDefinition.js test/files/v2/wrong-yaml-identation.js`
     );
 
     expect(result.stdout).toContain(

test/utils.spec.js

@@ -22,7 +22,7 @@ describe('Utilities module', () => {
   describe('extractAnnotations', () => {
     it('should extract jsdoc comments by default', () => {
       expect(
-        utils.extractAnnotations(require.resolve('../example/app/routes2.js'))
+        utils.extractAnnotations(require.resolve('../examples/app/routes2.js'))
       ).toEqual({
         yaml: [],
         jsdoc: [
@@ -34,7 +34,7 @@ describe('Utilities module', () => {
     it('should extract data from YAML files', () => {
       expect(
         utils.extractAnnotations(
-          require.resolve('../example/app/parameters.yaml')
+          require.resolve('../examples/app/parameters.yaml')
         )
       ).toEqual({
         yaml: [
@@ -45,7 +45,7 @@ describe('Utilities module', () => {
 
       expect(
         utils.extractAnnotations(
-          require.resolve('../example/app/parameters.yml')
+          require.resolve('../examples/app/parameters.yml')
         )
       ).toEqual({
         yaml: [
@@ -57,7 +57,9 @@ describe('Utilities module', () => {
 
     it('should extract jsdoc comments from coffeescript files/syntax', () => {
       expect(
-        utils.extractAnnotations(require.resolve('../example/app/route.coffee'))
+        utils.extractAnnotations(
+          require.resolve('../examples/app/route.coffee')
+        )
       ).toEqual({
         yaml: [],
         jsdoc: [