init

Author: OkayestDev

.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+.git

README.md

@@ -0,0 +1,80 @@
+#### Installation
+
+`npm i jest-doc`
+
+#### Configuration
+
+Creates [apidoc.js](https://apidocjs.com/) documentation from jest tests
+
+Create a jest-apidoc.json at project root with the following structure
+```
+{
+    "outFolder": string, // path to write apidoc to
+    "ignoreRoutes": string[], // array of routes to ignore
+}
+```
+
+From your tests, call `setApiResponse({ method, params, status, response })`. I recommend writing an api request wrapper like so (uses supertest):
+```
+const request = require('supertest');
+const { setApiResponse } = require('jest-apidoc');
+const server = require('./app');
+
+const apiRequest = async (
+  method,
+  url,
+  params = {},
+) => {
+  const loadedServer = request(server);
+  let requestBuilder;
+
+  switch (method) {
+    case GET:
+      requestBuilder = loadedServer.get(url).query(params);
+      break;
+    case POST:
+      requestBuilder = loadedServer.post(url).send(params);
+      break;
+    case DELETE:
+      requestBuilder = loadedServer.delete(url).send(params);
+      break;
+    case PUT:
+      requestBuilder = loadedServer.put(url).send(params);
+      break;
+    case PATCH:
+      requestBuilder = loadedServer.patch(url).send(params);
+      break;
+    default:
+      throw new Error(`No method for: ${method}`);
+  }
+
+  return requestBuilder
+    .set('Content-Type', 'application/json')
+    .then((res) => {
+        setApiResponse({ method, params, status: res.statusCode, response });
+        return res;
+    });
+};
+```
+
+Expects tests to be structured like:
+```
+describe('some-route.routes.js`, () => {
+    describe('GET /some-route', () => {
+        test('some functionality', async () => {
+            ...
+        });
+    });
+});
+```
+
+In your [test setup file](https://jestjs.io/docs/en/configuration#setupfilesafterenv-array), add the `writeApiDoc()` in the `afterAll()`
+
+```
+const { writeApiDoc } = require('jest-apidoc');
+
+afterAll(() => {
+    writeApiDoc();
+})
+```
+Above will write all response set through `writeApiResponse()` to the `outFolder` of `jest-apidoc.json`

index.js

@@ -0,0 +1,254 @@
+const fs = require("fs");
+const { outFolder, ignoreRoutes } = require("../../jest-apidoc.json");
+
+// prettier-ignore
+const baseSuccessfulExample =
+`@apiSuccessExample Success-Response:
+  HTTP/1.1 {{status}}{{response}}`;
+
+// prettier-ignore
+const baseErrorExample =
+`@apiErrorExample {json} Error-Response:
+  HTTP/1.1 {{status}}{{response}}`;
+
+// prettier-ignore
+const baseApiDoc =
+`/**
+  @api {{{method}}} {{route}} {{routeTitle}}
+  @apiName {{apiName}}
+  @apiGroup {{apiGroup}}
+{{params}}
+  {{successResponses}}{{errorResponses}}*/
+`;
+
+let lastTestName = "";
+let lastDescribeName = "";
+
+const originalTest = global.test;
+global.test = function (name, callback, timeout) {
+  lastTestName = name;
+  originalTest(name, callback, timeout);
+};
+
+const originalIt = global.it;
+global.it = function (name, callback, timeout) {
+  lastTestName = name;
+  originalIt(name, callback, timeout);
+};
+
+const originalDescribe = global.describe;
+global.describe = function (name, callback) {
+  lastDescribeName = name;
+  originalDescribe(name, callback);
+};
+
+/**
+ * current test name to be structured like "admin-session.routes PUT /admin/vendors/:vendorId updates and returns vendor"
+ * parse out PUT /admin/vendors/:vendorId
+ */
+const getDocNameFromTestName = (currentTestName) => {
+  const parts = currentTestName.split(" ");
+  return `${parts[2]}`;
+};
+
+const getGroupNameFromTestName = (currentTestName) => {
+  const parts = currentTestName.split(" ");
+  return parts[0].replace(".routes", "").replace("-", " ");
+};
+
+const getParamType = (paramValue) => {
+  if (Array.isArray(paramValue) && paramValue.length > 0) {
+    return `${typeof paramValue[0]}[]`;
+  }
+
+  if (paramValue && paramValue.constructor) {
+    const { name } = paramValue.constructor;
+    return name.toLowerCase();
+  }
+
+  return typeof paramValue;
+};
+
+const createParams = (params) => {
+  const paramsKeys = Object.keys(params);
+
+  if (paramsKeys.length === 0) {
+    return "";
+  }
+
+  let paramString = "";
+
+  paramsKeys.forEach((key) => {
+    const paramType = getParamType(params[key]);
+    paramString += `  @apiParam {${paramType}} ${key}\n`;
+  });
+
+  return `\n${paramString}`;
+};
+
+const createResponse = (response) => {
+  if (!response) {
+    return "";
+  }
+
+  delete response.status;
+  const jsonResponse = JSON.stringify(response, null, 2);
+  return `\n  ${jsonResponse}\n`;
+};
+
+/**
+ * apiCalls: {
+ *  [route]: {
+ *    [method]: {
+ *      docName,
+ *      apiGroup,
+ *      apiName,
+ *      routeTitle,
+ *      lastDescribeName,
+ *      lastTestName,
+ *      params: {},
+ *      statuses: {
+ *        [status]: {
+ *          response: {},
+ *        }
+ *      },
+ *    },
+ *  },
+ * }
+ */
+const apiCalls = {};
+
+const populateUndefined = ({ method, route, status }) => {
+  if (!apiCalls[route]) {
+    apiCalls[route] = {};
+  }
+
+  if (!apiCalls[route][method]) {
+    apiCalls[route][method] = {
+      params: {},
+      statuses: {},
+    };
+    apiCalls[route][method].statuses = {};
+  }
+
+  if (!apiCalls[route][method].statuses[status]) {
+    apiCalls[route][method].statuses[status] = {
+      response: {},
+    };
+  }
+};
+
+const setApiResponse = ({ method, params, status, response }) => {
+  const jestState = expect.getState();
+
+  const { currentTestName } = jestState;
+  const apiGroup = getGroupNameFromTestName(currentTestName);
+  const apiName = `${method.toUpperCase()} ${apiGroup}`;
+  const routeToWrite = lastDescribeName.split(" ")[1] || lastDescribeName;
+
+  if (!ignoreRoutes.includes(routeToWrite)) {
+    populateUndefined({ method, route: routeToWrite, status });
+
+    const { params: currentParams } = apiCalls[routeToWrite][method];
+    const { response: currentResponse } = apiCalls[routeToWrite][
+      method
+    ].statuses[status];
+
+    const paramsToWrite =
+      currentParams &&
+      Object.keys(currentParams).length > Object.keys(params).length
+        ? currentParams
+        : params;
+    const responseToWrite =
+      currentResponse &&
+      Object.keys(currentResponse).length > Object.keys(response).length
+        ? currentResponse
+        : response;
+
+    // @todo check response size too
+
+    apiCalls[routeToWrite][method] = {
+      docName: getDocNameFromTestName(currentTestName),
+      apiGroup,
+      apiName,
+      routeTitle: apiName,
+      lastDescribeName,
+      lastTestName,
+      params: paramsToWrite,
+      statuses: {
+        ...apiCalls[routeToWrite][method].statuses,
+        [status]: {
+          response: responseToWrite,
+        },
+      },
+    };
+  }
+};
+
+const writeApiDoc = () => {
+  // Create apidoc if non-existent
+  if (!fs.existsSync(outFolder)) {
+    fs.mkdirSync(outFolder);
+  }
+
+  const routes = Object.keys(apiCalls);
+
+  routes.forEach((apiRoute) => {
+    const methods = Object.keys(apiCalls[apiRoute]);
+    methods.forEach((apiMethod) => {
+      const { docName, apiGroup, apiName, routeTitle, params } = apiCalls[
+        apiRoute
+      ][apiMethod];
+
+      const statuses = Object.keys(apiCalls[apiRoute][apiMethod].statuses);
+
+      const successResponseDocs = [];
+      const errorResponseDocs = [];
+      const paramsString = createParams(params);
+
+      statuses.forEach((apiStatus) => {
+        const { response } = apiCalls[apiRoute][apiMethod].statuses[apiStatus];
+
+        const responseString = createResponse(response);
+
+        if (apiStatus < 400) {
+          successResponseDocs.push(
+            baseSuccessfulExample
+              .replace(/{{status}}/g, apiStatus)
+              .replace(/{{response}}/g, responseString)
+          );
+        } else {
+          errorResponseDocs.push(
+            baseErrorExample
+              .replace(/{{status}}/g, apiStatus)
+              .replace(/{{response}}/g, responseString)
+          );
+        }
+      });
+
+      const apiDoc = baseApiDoc
+        .replace(/{{routeTitle}}/g, routeTitle)
+        .replace(/{{params}}/g, paramsString)
+        .replace(/{{apiName}}/g, apiName)
+        .replace(/{{apiGroup}}/g, apiGroup)
+        .replace(/{{method}}/g, apiMethod.toUpperCase())
+        .replace(/{{route}}/g, docName)
+        .replace(/{{successResponses}}/g, successResponseDocs.join("\n"))
+        .replace(/{{errorResponses}}/g, errorResponseDocs.join("\n"));
+
+      const path = (docName.charAt(0) === "/" ? docName : `/${docName}`)
+        .replace(/\//g, "-")
+        .replace(/:/g, "");
+
+      fs.writeFileSync(
+        `${outFolder}/${apiMethod.toUpperCase()}-${path}.js`,
+        apiDoc
+      );
+    });
+  });
+};
+
+module.exports = {
+  setApiResponse,
+  writeApiDoc,
+};

package.json

@@ -0,0 +1,15 @@
+{
+  "name": "jest-apidoc",
+  "version": "1.0.0",
+  "description": "create apidoc from jest route tests",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+bitbucket.org:Kyle-Richardson/jest-apidoc.git"
+  },
+  "author": "Kyle Richardson",
+  "license": "ISC"
+}