Add support for webhooks (#47)

Author: eranelbaz

README.md

@@ -23,6 +23,7 @@ Works well with [Stoplight.io](https://stoplight.io/)
         - [`cookieParams`](#cookieparams)
         - [`requestModels`](#requestmodels)
         - [`methodResponses`](#methodresponses-and-responsemodels)
+        - [`webhooks`](#webhooks)
 - [Install](#install)
 
 ---
@@ -114,6 +115,7 @@ The `documentation` section of the event configuration can contain the following
 * `pathParams`: a list of path parameters (see [pathParams](#pathparams) below) - **these _can_ be autogenerated for you from TypeScript**
 * `cookieParams`: a list of cookie parameters (see [cookieParams](#cookieparams) below)
 * `methodResponses`: an array of response models and applicable status codes (see [methodResponses](#methodresponses-and-responsemodels)) - **these _will_ be autogenerated for you from TypeScript**
+* `webhooks`: an object with all the webhooks with descriptions (see [webhooks](#webhooks)) - **these _will_ be autogenerated for you from TypeScript**
 
 ```yml
 functions:
@@ -435,6 +437,68 @@ functions:
 
 Endpoints that are not attached to a custom tag, are still attached to the title ( which is the default tag ).
 
+#### `webhooks`
+OpenAPI have an option to add your application `webhooks`, while this feature isn't supported by `serverless`.
+
+For those the plugin will look for the webhooks under `custom.documentation.webhooks`.
+
+For example
+
+```yaml
+custom:
+  documentation:
+    apiNamespace: MyApi
+    webhooks:
+      WebhookName:
+        post:
+          requestBody:
+            description: |
+              This is a request body description
+          responses:
+            200:
+              description: |
+                This is a expected response description
+```
+
+this will generate the next OpenAPI file
+
+```yaml
+components:
+  schemas:
+    MyApi.Webhooks.WebhookName:
+      type: object
+webhooks:
+  WebhookName:
+    post:
+      requestBody:
+        description: |
+          This is a request body description
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MyApi.Webhooks.WebhookName'
+      responses:
+        '200':
+          description: |
+            This is a expected response description
+```
+
+With the next `api.d.ts`:
+
+```typescript
+export namespace MyApi {
+  export namespace Webhooks {
+    export type WebhookName = {
+      id: string,
+      name: string,
+      age: number
+      // ...
+    }
+  }
+}
+```
+
+
 ## Install
 
 This plugin is **an extension**.  

package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-openapi-typescript",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "An extension of @conqa/serverless-openapi-documentation that also generates your OpenAPI models from TypeScript",
   "main": "dist/index.js",
   "scripts": {
@@ -14,6 +14,7 @@
     "ts-json-schema-generator": "^1.1.2"
   },
   "devDependencies": {
+    "@types/node": "20.12.11",
     "@conqa/serverless-openapi-documentation": "^1.1.0",
     "@types/jest": "^27.0.1",
     "@types/serverless": "^1.78.35",

pnpm-lock.yaml

@@ -23,6 +23,7 @@ export default class ServerlessOpenapiTypeScript {
     private typescriptApiModelPath: string;
     private tsconfigPath: string;
     private schemaGenerator: SchemaGenerator;
+    private webhookEntries: Record<string, any> = {};
 
     constructor(private serverless: Serverless, private options: Options) {
         this.assertPluginOrder();
@@ -64,6 +65,10 @@ export default class ServerlessOpenapiTypeScript {
         return this.serverless.service.functions || {};
     }
 
+    get webhooks() {
+      return this.serverless.service.custom.documentation.webhooks || {};
+    }
+
     log(msg) {
         this.serverless.cli.log(`[serverless-openapi-typescript] ${msg}`);
     }
@@ -77,7 +82,7 @@ export default class ServerlessOpenapiTypeScript {
                     if (httpEvent.documentation) {
                         this.log(`Generating docs for ${functionName}`);
 
-                        this.setModels(httpEvent, functionName);
+                        this.setHttpMethodModels(httpEvent, functionName);
 
                         const paths = get(httpEvent, 'request.parameters.paths', []);
                         const querystrings = get(httpEvent, 'request.parameters.querystrings', {});
@@ -94,6 +99,16 @@ export default class ServerlessOpenapiTypeScript {
             });
         });
 
+        this.log('Scanning webhooks for documentation attribute');
+        Object.keys(this.webhooks).forEach(webhookName => {
+          const webhook = this.webhooks[webhookName];
+          const methodDefinition = webhook['post'];
+          if (methodDefinition) {
+            this.setWebhookModels(methodDefinition, webhookName);
+            this.log(`Generating docs for webhook ${webhookName}`);
+          }
+        });
+
         this.assertAllFunctionsDocumented();
     }
 
@@ -138,7 +153,7 @@ export default class ServerlessOpenapiTypeScript {
         });
     }
 
-    setModels(httpEvent, functionName) {
+    setHttpMethodModels(httpEvent, functionName) {
         const definitionPrefix = `${this.serverless.service.custom.documentation.apiNamespace}.${upperFirst(camelCase(functionName))}`;
         const method = httpEvent.method.toLowerCase();
         switch (method) {
@@ -179,10 +194,21 @@ export default class ServerlessOpenapiTypeScript {
         }
     }
 
+    setWebhookModels(webhook, webhookName: string) {
+      const webhookModelName = `${this.serverless.service.custom.documentation.apiNamespace}.Webhooks.${upperFirst(camelCase(webhookName))}`;
+      this.setModel(webhookModelName);
+      this.webhookEntries[webhookName] = {
+        post: webhook
+      };
+      // Since the original plugin doesn't read `webhooks` property and handle it we need to help it
+      set(this.webhookEntries[webhookName], 'post.requestBody.content', { 'application/json': { schema: { '$ref': `#/components/schemas/${webhookModelName}` } } });
+    }
+
     postProcessOpenApi() {
         // @ts-ignore
         const outputFile = this.serverless.processedInput.options.output;
         const openApi = yaml.load(fs.readFileSync(outputFile));
+        openApi['webhooks'] = this.webhookEntries;
         this.patchOpenApiVersion(openApi);
         this.enrichMethodsInfo(openApi);
         const encodedOpenAPI = this.encodeOpenApiToStandard(openApi);

src/serverless-openapi-typescript.ts

@@ -61,6 +61,7 @@ paths:
                 $ref: '#/components/schemas/ProjectApi.GetFunc.Response'
       tags:
         - BazTitle
+webhooks: {}
 tags:
   - name: Project
     description: DummyDescription

test/fixtures/expect-openapi-custom-tags.yml

@@ -37,7 +37,7 @@ components:
           type: string
         generic:
           $ref: >-
-            #/components/schemas/ProjectApi.GenericType_structure-1448918441-633-661-1448918441-620-662-1448918441-599-663-1448918441-547-673-1448918441-515-674-1448918441-283-680-1448918441-250-680-1448918441-104-1213-1448918441-75-1213-1448918441-0-1214_
+            #/components/schemas/ProjectApi.GenericType_structure-1448918441-758-786-1448918441-745-787-1448918441-724-788-1448918441-672-798-1448918441-640-799-1448918441-408-805-1448918441-376-805-1448918441-104-1338-1448918441-75-1338-1448918441-0-1339_
       required:
         - id
         - uuid
@@ -70,7 +70,18 @@ components:
       required:
         - data
       additionalProperties: false
-    ProjectApi.GenericType_structure-1448918441-633-661-1448918441-620-662-1448918441-599-663-1448918441-547-673-1448918441-515-674-1448918441-283-680-1448918441-250-680-1448918441-104-1213-1448918441-75-1213-1448918441-0-1214_:
+    ProjectApi.Webhooks.OnCreateWebhook:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+      required:
+        - id
+        - name
+      additionalProperties: false
+    ProjectApi.GenericType_structure-1448918441-758-786-1448918441-745-787-1448918441-724-788-1448918441-672-798-1448918441-640-799-1448918441-408-805-1448918441-376-805-1448918441-104-1338-1448918441-75-1338-1448918441-0-1339_:
       type: array
       items:
         type: object
@@ -83,6 +94,7 @@ components:
           - key
           - name
         additionalProperties: false
+
 info:
   title: Project
   description: >
@@ -220,6 +232,21 @@ paths:
                 $ref: '#/components/schemas/ProjectApi.GetFunc.Response'
       tags:
         - Project
+webhooks:
+  OnCreateWebhook:
+    post:
+      requestBody:
+        description: |
+          This is a request body description
+        content:
+          application/json:
+            schema:
+              $ref: >-
+                #/components/schemas/ProjectApi.Webhooks.OnCreateWebhook
+      responses:
+        '200':
+          description: |
+            This is a expected response description
 tags:
   - name: Project
     description: >

test/fixtures/expect-openapi-full.yml

@@ -61,6 +61,7 @@ paths:
                 $ref: '#/components/schemas/ProjectApi.GetFunc.Response'
       tags:
         - BazTitle
+webhooks: {}
 tags:
   - name: Project
     description: DummyDescription

test/fixtures/expect-openapi-hyphenated-functions.yml

@@ -48,6 +48,7 @@ paths:
                 $ref: '#/components/schemas/ProjectApi.Func.Response'
       tags:
         - Project
+webhooks: {}
 tags:
   - name: Project
     description: DummyDescription

test/fixtures/expect-openapi-query-param-type.yml

@@ -0,0 +1,40 @@
+openapi: 3.1.0
+components:
+  schemas:
+    ProjectApi.Webhooks.OnCreateWebhook:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+      required:
+        - id
+        - name
+      additionalProperties: false
+info:
+  title: Project
+  description: DummyDescription
+paths: { }
+webhooks:
+  OnCreateWebhook:
+    post:
+      requestBody:
+        description: |
+          This is a request body description
+        content:
+          application/json:
+            schema:
+              $ref: >-
+                #/components/schemas/ProjectApi.Webhooks.OnCreateWebhook
+      responses:
+        '200':
+          description: |
+            This is a expected response description
+tags:
+  - name: Project
+    description: DummyDescription
+  - name: FooBarTitle
+    description: FooBarDescription
+  - name: BazTitle
+    description: BazDescription

test/fixtures/expect-openapi-webhooks.yml

@@ -8,7 +8,12 @@ export namespace ProjectApi {
     export type Number = number
     export type String = string;
     export type GenericType<T> = T[];
-
+    export namespace Webhooks {
+      export type OnCreateWebhook = {
+        id: string;
+        name: string;
+      }
+    }
     export namespace CreateFunc {
         export namespace Request {
             export type Body = {

test/serverless-full/api.d.ts

@@ -20,6 +20,16 @@ custom:
 
       More on https://google.com
     apiNamespace: ProjectApi
+    webhooks:
+      OnCreateWebhook:
+        post:
+          requestBody:
+            description: |
+              This is a request body description
+          responses:
+            200:
+              description: |
+                This is a expected response description
 
 functions:
   createFunc:

test/serverless-full/resources/serverless.yml

@@ -16,6 +16,7 @@ describe('ServerlessOpenapiTypeScript', () => {
     ${'Custom Tags'}  | ${'custom-tags'}
     ${'Hyphenated Functions'}  | ${'hyphenated-functions'}
     ${'Full Project'} | ${'full'}
+    ${'Webhooks'} | ${'webhooks'}
     `('when using $testCase', ({projectName}) => {
 
         beforeEach(async () => {

test/serverless-openapi-typescript.spec.ts

@@ -0,0 +1,8 @@
+export namespace ProjectApi {
+  export namespace Webhooks {
+    export type OnCreateWebhook = {
+      id: string;
+      name: string;
+    }
+  }
+}

test/serverless-webhooks/api.d.ts

@@ -0,0 +1,30 @@
+service: serverless-openapi-typescript-demo
+provider:
+  name: aws
+
+plugins:
+  - ../node_modules/@conqa/serverless-openapi-documentation
+  - ../src/index
+
+custom:
+  documentation:
+    title: 'Project'
+    description: DummyDescription
+    apiNamespace: ProjectApi
+    tags:
+       - name: FooBarTitle
+         description: FooBarDescription
+       - name: BazTitle
+         description: BazDescription
+    webhooks:
+      OnCreateWebhook:
+        post:
+          requestBody:
+            description: |
+              This is a request body description
+          responses:
+            200:
+              description: |
+                This is a expected response description
+
+