add jsdocs to declared operations

Author: omermecitoglu

src/core/resolvers/declared-operation.ts

@@ -1,22 +1,27 @@
 import getContentSchema from "./content";
 import resolveEndpoints from "./enpoint";
 import { defaultOperationName } from "./operation-name";
-import { resolveOperationParams } from "./operation-param";
+import { resolveDocParams, resolveOperationParams } from "./operation-param";
 import { getResponse } from "./response";
 import { resolveSchema } from "./schema-definition";
 import type { PathsObject } from "@omer-x/openapi-types/paths";
 import type { ResponsesObject } from "@omer-x/openapi-types/response";
 
 export type DeclaredOperation = {
   name: string,
+  desription: string,
   parameters: string,
+  docParams: {
+    name: string,
+    type: string,
+    description: string,
+  }[],
   result: string,
 };
 
 function resolveOperationResult(responses?: ResponsesObject) {
   if (!responses) return "unknown";
   const schemas = Object.values(responses).map(resp => {
-    if (!resp) return null;
     const response = getResponse(resp);
     if (!response.content) return null;
     const schema = getContentSchema(response.content);
@@ -29,7 +34,9 @@ function resolveOperationResult(responses?: ResponsesObject) {
 export function resolveDeclaredOperations(paths: PathsObject, framework: string | null) {
   return resolveEndpoints(paths).map<DeclaredOperation>(({ method, path, operation }) => ({
     name: operation.operationId || defaultOperationName(method, path),
+    desription: operation.description || "missing-description",
     parameters: resolveOperationParams(operation, method, true, framework).join(", "),
+    docParams: resolveDocParams(operation, method, framework),
     result: resolveOperationResult(operation.responses),
   }));
 }

src/core/resolvers/operation-param.ts

@@ -53,6 +53,41 @@ export function resolveOperationParams(operation: OperationObject, method: strin
   return collection;
 }
 
+function resolveDocParam(parameter: ParameterObject | ReferenceObject) {
+  const param = getParameter(parameter);
+  return {
+    name: param.name,
+    type: resolveSchema(param.schema),
+    description: param.description || "missing-description",
+  };
+}
+
+export function resolveDocParams(operation: OperationObject, method: string, framework: string | null) {
+  const resolvedParams = (operation.parameters ?? [])
+    .filter(param => "in" in param && (param.in === "path" || param.in === "query"))
+    .toSorted(sortRequiredParamsFirst)
+    .map(resolveDocParam);
+  const collection = [
+    ...resolvedParams,
+  ];
+  if (operation.requestBody) {
+    const body = getBodyRequest(operation.requestBody);
+    collection.push({
+      name: hasFormData(operation) ? "formBody" : "requestBody",
+      type: resolveSchema(getContentSchema(body.content)),
+      description: "Request body",
+    });
+  }
+  if (framework === "next" && method.toUpperCase() === "GET") {
+    collection.unshift({
+      name: "cacheTag",
+      type: "string | null",
+      description: "Tag name of Next.js fetch cache",
+    });
+  }
+  return collection;
+}
+
 export function getParameter(source: ParameterObject | ReferenceObject) {
   if ("$ref" in source) throw new Error("Parameter references not implemented yet.");
   return source;

src/templates/declaration.hbs

@@ -2,5 +2,11 @@
 import type {{this}} from "./schemas/{{this}}";
 {{/each}}
 {{#each operations}}
+/**
+ * {{desription}}
+{{#each docParams}}
+ * @param { {{~type~}} } {{name}} - {{description}}
+{{/each}}
+ */
 export declare function {{name}}({{{parameters}}}): Promise<{{result}}>;
 {{/each}}