add documentation generator

Author: omermecitoglu

src/core/capitalize.ts

@@ -0,0 +1,3 @@
+export default function capitalize(text: string) {
+  return text.split(" ").map(word => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}

src/core/renderers/documentation.ts

@@ -0,0 +1,35 @@
+import Handlebars from "handlebars";
+import type { OpenAPI } from "~/core/openapi";
+import { type DocumentedOperation, resolveDocumentedOperations } from "~/core/resolvers/documented-operation";
+import getTemplate from "~/core/template";
+import documentationTemplate from "~/templates/documentation.hbs";
+
+type DocumentationTemplate = {
+  serviceName: string,
+  packageName: string,
+  envName: string,
+  operations: DocumentedOperation[],
+};
+
+export default function generateDocumentation(
+  serviceName: string,
+  packageName: string,
+  envName: string,
+  paths: OpenAPI["paths"]
+) {
+  const template = getTemplate<DocumentationTemplate>(documentationTemplate);
+  return template({
+    serviceName,
+    packageName,
+    envName,
+    operations: resolveDocumentedOperations(paths),
+  });
+}
+
+Handlebars.registerHelper("serialize", (input: string) => {
+  return input
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, "")
+    .trim()
+    .replace(/\s+/g, "-");
+});

src/core/resolvers/documented-operation.ts

@@ -0,0 +1,54 @@
+import type { OpenAPI, Operation } from "~/core/openapi";
+import getContentSchema from "./content";
+import resolveEndpoints from "./enpoint";
+import { resolveResponsesForDocs } from "./response";
+import { resolveSchema } from "./schema-definition";
+
+type DocumentedParam = {
+  name: string,
+  description: string,
+  type: string,
+  optional: boolean,
+};
+
+type DocumentedException = {
+  statusCode: string,
+  description: string,
+};
+
+export type DocumentedOperation = {
+  name: string,
+  summary: string,
+  description: string,
+  parameters: string,
+  parametersRaw: DocumentedParam[],
+  result: string,
+  exceptions: DocumentedException[],
+};
+
+export function resolveDocumentedOperations(paths: OpenAPI["paths"]) {
+  return resolveEndpoints(paths).map<DocumentedOperation>(({ operation }) => {
+    const parameters = (operation.parameters ?? []).map<DocumentedParam>(p => ({
+      name: p.name,
+      description: p.description,
+      type: resolveSchema(p.schema),
+      optional: !p.required,
+    }));
+    return {
+      name: operation.operationId,
+      summary: operation.summary,
+      description: operation.description,
+      parameters: parameters.map(p => p.name).join(", "),
+      parametersRaw: parameters,
+      result: resolveOperationResult(operation.responses),
+      exceptions: resolveResponsesForDocs(operation.responses).filter(r => !r.statusCode.startsWith("2")),
+    };
+  });
+}
+
+function resolveOperationResult(responses: Operation["responses"]) {
+  const schemas = Object.values(responses).map(response => {
+    return response.content ? resolveSchema(getContentSchema(response.content)) : null;
+  });
+  return schemas.find(s => typeof s === "string") ?? "unknown";
+}

src/core/resolvers/response.ts

@@ -24,3 +24,10 @@ export function resolveResponses(responses: Operation["responses"]) {
     `case ${statusCode}: ${handleResponse(statusCode, response, false)};`
   ));
 }
+
+export function resolveResponsesForDocs(responses: Operation["responses"]) {
+  return Object.entries(responses).map(([statusCode, response]) => ({
+    statusCode,
+    description: response.description,
+  }));
+}

src/index.ts

@@ -3,8 +3,10 @@ import "~/core/renderers/parameter";
 import path from "node:path";
 import getAppName from "./core/app";
 import getArgument from "./core/arguments";
+import capitalize from "./core/capitalize";
 import createFile from "./core/file";
 import generateDeclaration from "./core/renderers/declaration";
+import generateDocumentation from "./core/renderers/documentation";
 import generateInterface from "./core/renderers/interface";
 import generateSchema from "./core/renderers/schema";
 import { resolveSchemas, resolveSchemasFromProps } from "./core/resolvers/imported-schema";
@@ -31,6 +33,7 @@ import generateSwaggerJson from "./core/swagger";
 
   const packageName = getAppName();
   const appName = packageName.split("/").pop() ?? "unknown-service";
+  const serviceName = capitalize(appName.replace(/-/g, " "));
   const envName = `${appName.replace(/-/g, "_").toUpperCase()}_BASE_URL`;
 
   const schemas = resolveSchemas(data.paths);
@@ -41,4 +44,7 @@ import generateSwaggerJson from "./core/swagger";
 
   const declaration = generateDeclaration(schemas, data.paths);
   await createFile(declaration, "index.d.ts", outputDir);
+
+  const doc = generateDocumentation(serviceName, packageName, envName, data.paths);
+  await createFile(doc, "README.md", process.cwd());
 })();

src/templates/documentation.hbs

@@ -0,0 +1,60 @@
+# {{serviceName}}
+
+Streamline your interactions with {{serviceName}} using this comprehensive service interface. Simplify integration and boost efficiency for seamless development.
+
+## Installation
+To use the {{serviceName}}, follow these steps:
+
+1. Install the `{{packageName}}` package using npm:
+```bash
+npm install {{packageName}}
+```
+
+2. Set up the `{{envName}}` environment variable in your project's `.env` file. This variable should contain the base URL for the {{serviceName}}.
+
+```dotenv
+{{envName}}=http://localhost:XXXX
+```
+
+Now you're ready to use the {{serviceName}} in your project!
+
+## Content
+{{#each operations}}
+- [{{summary}}](#{{serialize summary}})
+{{/each}}
+
+---
+
+{{#each operations}}
+## {{summary}}
+
+{{description}}
+
+### Example Usage:
+```typescript
+import { {{name}} } from "{{../packageName}}";
+
+const result = await {{name}}({{parameters}});
+```
+
+{{#if parametersRaw.length}}
+### Parameters:
+{{#each parametersRaw}}
+- **{{name}}** `({{type}})` {{description}} {{#if optional}}`(Optional)`{{/if}}
+{{/each}}
+{{/if}}
+
+### Returns:
+- `{{result}}`
+
+{{#if exceptions.length}}
+### Exceptions:
+{{#each exceptions}}
+- `{{statusCode}}` {{description}}
+{{/each}}
+{{/if}}
+
+---
+
+{{/each}}
+If you have any questions or need further assistance, feel free to reach out.