feat: Print OpenAPI docs for mocks

Author: igorjacauna

src/index.ts

@@ -1,6 +1,6 @@
 import { type AxiosInstance } from 'axios';
 import Proxy from './runtime/proxy';
 
-export function defineProxy(apiInstance: AxiosInstance) {
-  return new Proxy(apiInstance);
+export function defineProxy(apiInstance: AxiosInstance, generateDocs = false) {
+  return new Proxy(apiInstance, generateDocs);
 }

src/runtime/docGenerator.ts

@@ -0,0 +1,104 @@
+interface MockResponse {
+  status: number;
+  body: any;
+}
+
+interface MockEndpoint {
+  method: string;
+  path: string;
+  response: MockResponse;
+}
+
+interface OpenAPI {
+  openapi: string;
+  info: {
+    title: string;
+    version: string;
+  };
+  paths: Record<string, any>;
+}
+
+export class DocGenerator {
+  private mocks: MockEndpoint[] = [];
+
+  private filename: string;
+
+  constructor(filename = 'openapi.json') {
+    this.filename = filename;
+  }
+
+  /**
+   * Adiciona um novo mock e automaticamente atualiza o JSON de documentação
+   * @param method - Método HTTP (GET, POST, etc.)
+   * @param path - Endpoint da API
+   * @param status - Código de status HTTP da resposta
+   * @param body - Corpo da resposta
+   */
+  public addMock(
+    method: string,
+    path: string,
+    status: number,
+    body: any,
+  ): void {
+    // Verifica se já existe um mock com o mesmo método e path para evitar duplicação
+    const existingMockIndex = this.mocks.findIndex(
+      mock => mock.method === method.toUpperCase() && mock.path === path,
+    );
+
+    if (existingMockIndex !== -1) {
+      // Se já existe, atualiza o mock existente
+      this.mocks[existingMockIndex] = {
+        method: method.toUpperCase(),
+        path,
+        response: { status, body },
+      };
+    } else {
+      // Caso contrário, adiciona um novo mock
+      this.mocks.push({
+        method: method.toUpperCase(),
+        path,
+        response: { status, body },
+      });
+    }
+
+    // Regenera a documentação automaticamente
+    this.generateOpenApiJson();
+  }
+
+  /**
+   * Gera o JSON de documentação OpenAPI e salva no arquivo definido no construtor
+   */
+  private generateOpenApiJson(): void {
+    const openAPI: OpenAPI = {
+      openapi: '3.0.0',
+      info: {
+        title: 'Mocked API',
+        version: '1.0.0',
+      },
+      paths: {},
+    };
+
+    // Construindo os endpoints no formato OpenAPI
+    this.mocks.forEach(({ method, path, response }) => {
+      if (!openAPI.paths[path]) {
+        openAPI.paths[path] = {};
+      }
+
+      openAPI.paths[path][method.toLowerCase()] = {
+        summary: `Mock response for ${method} ${path}`,
+        responses: {
+          [response.status]: {
+            description: `Mock response for ${method} ${path}`,
+            content: {
+              'application/json': response.body,
+            },
+          },
+        },
+      };
+    });
+
+    console.log('\n\n## OpenAPI JSON ##');
+    console.log(JSON.stringify(openAPI, null, 2));
+    console.log('\n\n');
+  }
+}

src/runtime/handler.ts

@@ -4,6 +4,7 @@ import type {
   ResponseChanger,
   RouteConfig,
 } from '../types';
+import { DocGenerator } from './docGenerator';
 import {
   ejectFromRequest,
   ejectFromResponse,
@@ -21,16 +22,20 @@ export default class Handler {
 
   params?: object;
 
+  docGenerator?: DocGenerator;
+
   constructor(
     scope: Proxy,
     verb: string,
     path: string | RegExp,
     params?: object,
+    docGenerator?: DocGenerator,
   ) {
     this.scope = scope;
     this.verb = verb;
     this.path = path;
     this.params = params;
+    this.docGenerator = docGenerator;
   }
 
   private setProxy(
@@ -71,7 +76,6 @@ export default class Handler {
                 config,
                 request: requestConfig,
               };
-
               if (status < 400) resolve(response);
               else reject(response);
             });
@@ -139,11 +143,13 @@ export default class Handler {
 
   reply(statusCodeOrConfig: number | RouteConfig, mock?: unknown) {
     this.setProxy(statusCodeOrConfig, mock);
+    this.addMockDoc(statusCodeOrConfig, mock);
     return this.scope;
   }
 
   replyOnce(statusCodeOrConfig: number | RouteConfig, mock?: unknown) {
     this.setProxy(statusCodeOrConfig, mock, true);
+    this.addMockDoc(statusCodeOrConfig, mock);
     return this.scope;
   }
 
@@ -176,4 +182,21 @@ export default class Handler {
     this.setChangerResponseData<T>(changer, true);
     return this;
   }
+
+  addMockDoc(statusCodeOrFunction: number | RouteConfig, mock?: unknown) {
+    if (typeof statusCodeOrFunction === 'function') {
+      Promise.resolve(statusCodeOrFunction()).then(result => {
+        const [status, data] = result;
+        this.docGenerator?.addMock(
+          this.verb,
+          this.path.toString(),
+          status,
+          data,
+        );
+      });
+      return;
+    }
+    const status = statusCodeOrFunction;
+    this.docGenerator?.addMock(this.verb, this.path.toString(), status, mock);
+  }
 }

src/runtime/proxy.ts

@@ -1,4 +1,5 @@
 import type { AxiosInstance } from 'axios';
+import { DocGenerator } from './docGenerator';
 import Handler from './handler';
 import { clearAll } from './helpers';
 
@@ -11,12 +12,15 @@ export default class Proxy {
 
   params?: object;
 
-  constructor(axios: AxiosInstance) {
+  docGenerator?: DocGenerator;
+
+  constructor(axios: AxiosInstance, generateDocs = false) {
     this.axios = axios;
+    if (generateDocs) this.docGenerator = new DocGenerator();
   }
 
   private setup(verb: string, path: string | RegExp, params?: object) {
-    const handler = new Handler(this, verb, path, params);
+    const handler = new Handler(this, verb, path, params, this.docGenerator);
     return handler;
   }
 

test/index.test.ts

@@ -489,5 +489,25 @@ describe('axios-dev-proxy tests', () => {
       expect(server.isDone()).toBe(true);
       expect(server2.isDone()).toBe(true);
     });
+
+    it('should print docs once', async () => {
+      const documentedProxy = defineProxy(api, true);
+      server
+        .get('/generate-doc')
+        .reply(200, { data: 1 })
+        .get('/generate-doc-2')
+        .reply(200, { data: 2 });
+      const consoleLog = vi.spyOn(console, 'log');
+      documentedProxy.onGet('/generate-doc').reply(200, {
+        data: 'doc-1',
+      });
+      documentedProxy
+        .onGet('/generate-doc-2')
+        .reply(() => [201, { data: 'doc-2' }]);
+
+      await api.get('/generate-doc');
+      await api.get('/generate-doc-2');
+      expect(consoleLog).toBeCalled();
+    });
   });
 });