first version that works

Author: wwayne

.eslintignore

@@ -1 +1,2 @@
-lib/
+lib/
+bin/

.npmignore

@@ -1 +1,3 @@
-src/
+src/
+test/
+tsconfig.json

bin/outdoc.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const { Command } = require('commander');
+const { runner }  = require('../lib/index');
+
+const main = async () => {
+  const program = new Command();
+  // TODO: more options or config in package.json
+  program
+    .name('outdoc')
+    .description('Generate OpenAPI document from local testing')
+    .usage("[command running test] [options]")
+    .option('-o, --output', 'file path of the generated doc, format supports json and yaml, default: api.yaml')
+    .option('-t, --title <string>', 'title of the api document, default: API Document')
+    .option('-v, --version <string>', 'version of the api document, default: 1.0.0')
+    .option('-e, --email <string>', 'contact information')
+    .parse();
+
+  const args = program.args;
+  const opts = program.opts();
+
+  await runner(args, opts);
+};
+
+main();

package.json

@@ -1,15 +1,19 @@
 {
   "name": "outdoc",
-  "version": "0.0.1",
+  "version": "0.0.19",
   "description": "Auto-generate OpenAPI document for Node.js service from the local testing",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
+  "bin": {
+    "outdoc": "./bin/outdoc.js"
+  },
   "scripts": {
     "lint": "eslint .",
     "lint-fix": "eslint . --fix",
     "test": "env TS_NODE_COMPILER_OPTIONS='{\"module\": \"commonjs\" }' mocha -r ts-node/register '**/*.test.*'",
     "prebuild": "rimraf lib",
-    "build": "tsc --build"
+    "build": "tsc --build",
+    "prepublishOnly": "npm run build"
   },
   "repository": {
     "type": "git",
@@ -45,6 +49,7 @@
   "dependencies": {
     "commander": "^9.4.0",
     "content-type": "^1.0.4",
+    "js-yaml": "^4.1.0",
     "qs": "^6.11.0"
   }
 }

src/APICollector.interface.ts

@@ -0,0 +1,13 @@
+import type { OpenAPIV3_1 } from 'openapi-types';
+import type { ServerResponseArg, ObjectForResBodyBufferItem } from './types/asyncEventTypes';
+
+export type API_URL = string
+
+export interface APICollectorInterface {
+  addAPIItem(
+    serverResponse: ServerResponseArg,
+    resBody?: ObjectForResBodyBufferItem
+  ): void;
+
+  getItems(): Record<API_URL, OpenAPIV3_1.PathItemObject>;
+}

src/APICollector.ts

@@ -3,10 +3,9 @@ import qs from 'qs';
 import contentType from 'content-type';
 import type { OpenAPIV3_1 } from 'openapi-types';
 import type { ServerResponseArg, ObjectForResBodyBufferItem } from './types/asyncEventTypes';
+import type { API_URL, APICollectorInterface } from './APICollector.interface';
 
-type API_URL = string
-
-export default class APICollector {
+export default class APICollector implements APICollectorInterface {
   private items: Record<API_URL, OpenAPIV3_1.PathItemObject>;
 
   constructor () {
@@ -60,9 +59,9 @@ export default class APICollector {
     let path = parsedURL.pathname;
     if (!path) return;
     if (serverRes.req.params) {
-      // convert /path/xxx-xxx-xxx-xxx => /path/:id
+      // convert /path/xxx-xxx-xxx-xxx => /path/{id}
       Object.entries(serverRes.req.params).forEach(([key, value]) => {
-        path = path!.replace(value, `:${key}`);
+        path = path!.replace(value, `{${key}}`);
       });
     }
     return path;
@@ -83,16 +82,12 @@ export default class APICollector {
   }
 
   private extractHeaders (serverRes: ServerResponseArg): Array<OpenAPIV3_1.ParameterObject> {
-    const excludeHeaders = ['host', 'user-agent', 'content-length'];
+    const excludeHeaders = ['host', 'user-agent', 'content-length', 'content-type', 'accept'];
     const headers = this.genHeaderObjFromRawHeaders(
       serverRes.req.rawHeaders,
       { exclude: excludeHeaders }
     );
     return Object.entries(headers)
-      .filter(([key, value]) => {
-        if (key.toLowerCase() === 'accept' && value === "*/*") return false;
-        return true;
-      })
       .map(([key, value]) => ({
         in: 'header',
         name: key,
@@ -126,6 +121,7 @@ export default class APICollector {
     return Object.entries(serverRes.req.params).map(([key, value]) => ({
       in: 'path',
       name: key,
+      required: true,
       example: value,
       schema: {
         type: 'string'

src/APIGenerator.ts

@@ -1,5 +1,46 @@
+import { mkdir, writeFile } from 'fs/promises';
+import path from 'path';
+
+import type { OpenAPIV3_1 } from 'openapi-types';
+import type { API_URL, APICollectorInterface } from './APICollector.interface';
+
+type GenDocOpts = {
+  output?: string,
+  title?: string,
+  version?: string,
+  email?: string
+}
+
+const SUPPORTED_FORMAT = ['json', 'yaml'];
+
 export default class APIGenerator {
-  public generate (): void {
-    console.log('here')
+  public static async generate (
+    apiCollector: APICollectorInterface,
+    opts: GenDocOpts
+  ): Promise<void> {
+    const apiItems = apiCollector.getItems();
+    const paths = Object.entries(apiItems)
+      .reduce((acc, cur) => {
+        const key: API_URL = cur[0];
+        const value: OpenAPIV3_1.PathItemObject = cur[1];
+        acc[key] = value;
+        return acc;
+      }, {} as Record<string, any>);
+    const info = {
+      title: opts.title || 'API Document',
+      version: opts.version || '1.0.0',
+      ... opts.email && { contact: { email: opts.email } }
+    };
+    const apiDoc: OpenAPIV3_1.Document = {
+      openapi: '3.0.1',
+      info,
+      paths
+    };
+
+    const output = opts.output || 'api.json';
+    const fileFormat = path.extname(output);
+    // TODO: change format based on fileFormat
+    await mkdir(path.dirname(output), { recursive: true });
+    await writeFile(output, JSON.stringify(apiDoc, null, 2));
   }
 }

src/RequestHook.ts

@@ -1,71 +1,116 @@
-import async_hooks, { AsyncHook } from 'async_hooks';
+import {
+  PREFIX_RESPONSE_BODY_DATA,
+  PREFIX_SERVER_RESPONSE
+} from './constants';
 import type {
-  ObjectForResBodyArg,
   ObjectForResBodyBufferItem,
   ServerResponseArg
 } from './types/asyncEventTypes';
-import APICollector from './APICollector';
+import type { APICollectorInterface } from './APICollector.interface';
 
 /**
  * The response body data comes before ServerResponse event
  * The ServerResponse event will tell which asyncId it triggered
- * By this way we can get the full API data including req and res
+ * By this way we can get the full response
  */
 type EventMap = Record<number, ObjectForResBodyBufferItem | undefined>
 
+type ResponseBodyDataFromChildProcess = {
+  asyncId: number,
+  data: ObjectForResBodyBufferItem
+}
+
+type ServerResponseFromChildProcess = {
+  triggerAsyncId: number,
+  data: ServerResponseArg
+}
+
 export default class RequestHook {
-  private asyncHook: AsyncHook | null;
   private eventMap: EventMap;
-  private apiCollector: APICollector;
 
-  constructor () {
-    this.asyncHook = null;
-    this.eventMap = {};
-    this.apiCollector = new APICollector();
-  }
+  public static getInjectedCodes (): string {
+    return `
+      const async_hooks = require('async_hooks')
+      const asyncHook = async_hooks.createHook({ init });
+      asyncHook.enable();
 
-  public enable (): void {
-    this.asyncHook = async_hooks.createHook({ init: this.init });
-    this.asyncHook.enable();
-  }
+      function init(asyncId, type, triggerAsyncId, resource) {
+        if (type === "TickObject" && resource.args) {
+          const className = resource.args?.[0]?.constructor.name;
 
-  public disable (): void {
-    if (this.asyncHook) {
-      this.asyncHook.disable();
-      this.asyncHook = null;
-    }
-  }
+          // Response body data
+          if (className === "Object") {
+            const arg = resource.args[0]
+            if (arg?.stream?.server && arg?.state?.buffered) {
+              const dataItem = arg.state.buffered.find(item => {
+                if (!item) return false
+                return ['buffer', 'utf-8'].includes(item.encoding)
+              })
+              if (dataItem) {
+                const chunk = dataItem.encoding === 'buffer'
+                  ? dataItem.chunk.toString()
+                  : dataItem.chunk
+                const res = {
+                  asyncId,
+                  data: {
+                    encoding: dataItem.encoding,
+                    chunk
+                  }
+                }
+                console.log("${PREFIX_RESPONSE_BODY_DATA}" + JSON.stringify(res))
+              }
+            }
+          }
 
-  private extractResBody (arg: ObjectForResBodyArg): ObjectForResBodyBufferItem | undefined {
-    return arg.state.buffered.find(item => ['buffer', 'utf-8'].includes(item.encoding));
+          // Server response
+          if (className === "ServerResponse") {
+            const arg = resource.args[0];
+            const res = {
+              triggerAsyncId,
+              data: {
+                _header: arg._header,
+                statusCode: arg.statusCode,
+                statusMessage: arg.statusMessage,
+                req: {
+                  rawHeaders: arg.req.rawHeaders,
+                  url: arg.req.url,
+                  method: arg.req.method,
+                  params: arg.req.params,
+                  query: arg.req.query,
+                  baseUrl: arg.req.baseUrl,
+                  originalUrl: arg.req.originalUrl,
+                  body: arg.req.body
+                }
+              }
+            }
+            if (arg.req._readableState?.buffer?.head?.data) {
+              res.data.req._readableState = {
+                buffer: {
+                  head: {
+                    data: arg.req._readableState.buffer.head.data.toString()
+                  }
+                }
+              }
+            }
+            console.log("${PREFIX_SERVER_RESPONSE}" + JSON.stringify(res))
+          }
+        }
+      }
+    `;
   }
 
-  private init (
-    asyncId: number,
-    type: string,
-    triggerAsyncId: number,
-    resource: {
-      args: Array<ObjectForResBodyArg | ServerResponseArg>
-    }
-  ): void {
-    if (type === "TickObject" && resource.args) {
-      const className = resource.args?.[0]?.constructor.name;
+  constructor (private apiCollector: APICollectorInterface) {
+    this.eventMap = {};
+  }
 
-      // Check if it is response data, save it into eventMap
-      if (className === "Object") {
-        const myArg = resource.args[0] as ObjectForResBodyArg;
-        if (myArg?.stream?.server) {
-          this.eventMap[asyncId] = this.extractResBody(myArg);
-        }
-      }
+  public handleResponseBodyData (res: ResponseBodyDataFromChildProcess): void {
+    this.eventMap[res.asyncId] = res.data;
+  }
 
-      // Check if it is server response, pass it to APICollector
-      if (className === "ServerResponse") {
-        const myArg = resource.args[0] as ServerResponseArg;
-        const responseBodyData = this.eventMap[triggerAsyncId];
-        this.apiCollector.addAPIItem(myArg, responseBodyData);
-        delete this.eventMap[triggerAsyncId];
-      }
-    }
+  public handleServerResponse (res: ServerResponseFromChildProcess): void {
+    const triggerAsyncId = res.triggerAsyncId;
+    const responseBodyData = this.eventMap[triggerAsyncId];
+    this.apiCollector.addAPIItem(res.data, responseBodyData);
+    delete this.eventMap[triggerAsyncId];
   }
 }

src/constants.ts

@@ -0,0 +1,2 @@
+export const PREFIX_RESPONSE_BODY_DATA = 'outdoc response body data -';
+export const PREFIX_SERVER_RESPONSE = 'outdoc server response -';