Fix breaking JSDoc changes (#1012) (#1029)

* Fix #1012

* Update examples

* Fix the operation comment

* Fix subschemas (digital ocean)

* indentation

* Fix lints and examples

Author: mitchell-merry

examples/digital-ocean-api.ts

@@ -9,7 +9,7 @@ import transformParameterObject from "./transform/parameter-object.js";
 import transformRequestBodyObject from "./transform/request-body-object.js";
 import transformResponseObject from "./transform/response-object.js";
 import transformSchemaObject from "./transform/schema-object.js";
-import { error, escObjKey, getDefaultFetch, getEntries, indent } from "./utils.js";
+import { error, escObjKey, getDefaultFetch, getEntries, getSchemaObjectComment, indent } from "./utils.js";
 export * from "./types.js"; // expose all types to consumers
 
 const EMPTY_OBJECT_RE = /^\s*\{?\s*\}?\s*$/;
@@ -125,6 +125,7 @@ async function openapiTS(
       const key = escObjKey(subschemaID);
       const path = `${subschemaID}#`;
       let subschemaOutput = "";
+      let comment: string | undefined;
       switch (subschema.hint) {
         case "OpenAPI3": {
           const subschemaTypes = transformSchema(subschema.schema, { ...ctx, indentLv });
@@ -144,6 +145,7 @@ async function openapiTS(
           break;
         }
         case "OperationObject": {
+          comment = getSchemaObjectComment(subschema.schema, indentLv);
           subschemaOutput = transformOperationObject(subschema.schema, { path, ctx: { ...ctx, indentLv } });
           break;
         }
@@ -169,6 +171,7 @@ async function openapiTS(
         }
       }
       if (subschemaOutput && !EMPTY_OBJECT_RE.test(subschemaOutput)) {
+        if (comment) output.push(indent(comment, indentLv));
         output.push(indent(`${key}: ${subschemaOutput}`, indentLv));
       }
       delete allSchemas[subschemaID];
@@ -182,8 +185,9 @@ async function openapiTS(
   // 3. operations (only get fully built after all external schemas transformed)
   if (Object.keys(ctx.operations).length) {
     output.push(options.exportType ? "export type operations = {" : "export interface operations {", "");
-    for (const k of Object.keys(ctx.operations)) {
-      output.push(indent(`${escObjKey(k)}: ${ctx.operations[k]};`, 1));
+    for (const [key, { operationType, comment }] of Object.entries(ctx.operations)) {
+      if (comment) output.push(indent(comment, 1));
+      output.push(indent(`${escObjKey(key)}: ${operationType};`, 1));
     }
     output.push(`}${options.exportType ? ";" : ""}`, "");
   } else {

examples/github-api-next.ts

@@ -30,8 +30,6 @@ export default function transformOperationObject(
   let { indentLv } = ctx;
   const output: string[] = wrapObject ? ["{"] : [];
   indentLv++;
-  const c = getSchemaObjectComment(operationObject, indentLv);
-  if (c) output.push(indent(c, indentLv));
 
   // parameters
   {
@@ -51,7 +49,7 @@ export default function transformOperationObject(
               key = tsOptionalProperty(key);
             }
             const c = getSchemaObjectComment(p, indentLv);
-            if (c) parameterOutput.push(indent(c, indentLv));
+            if (c) inlineOutput.push(indent(c, indentLv));
             const parameterType = transformParameterObject(p, {
               path: `${path}/parameters/${p.name}`,
               ctx: { ...ctx, indentLv },

examples/github-api.ts

@@ -30,7 +30,10 @@ export default function transformPathItemObject(
     // if operationId exists, move into an `operations` export and pass the reference in here
     else if (operationObject.operationId) {
       const operationType = transformOperationObject(operationObject, { path, ctx: { ...ctx, indentLv: 1 } });
-      ctx.operations[operationObject.operationId] = operationType;
+      ctx.operations[operationObject.operationId] = {
+        operationType,
+        comment: getSchemaObjectComment(operationObject, 1),
+      };
       output.push(indent(`${method}: operations[${escStr(operationObject.operationId)}];`, indentLv));
     } else {
       const operationType = transformOperationObject(operationObject, { path, ctx: { ...ctx, indentLv } });

examples/octokit-ghes-3.6-diff-to-api.ts

@@ -638,7 +638,13 @@ export interface GlobalContext {
   postTransform: OpenAPITSOptions["postTransform"];
   immutableTypes: boolean;
   indentLv: number;
-  operations: Record<string, string>;
+  operations: Record<
+    string,
+    {
+      comment?: string;
+      operationType: string;
+    }
+  >;
   pathParamsAsTypes: boolean;
   silent: boolean;
   supportArrayLength: boolean;

examples/stripe-api.ts

@@ -1,4 +1,4 @@
-import type { PathItemObject } from "../src/types";
+import type { GlobalContext, PathItemObject } from "../src/types";
 import transformPathItemObject, { TransformPathItemObjectOptions } from "../src/transform/path-item-object.js";
 
 const options: TransformPathItemObjectOptions = {
@@ -23,6 +23,7 @@ describe("Path Item Object", () => {
   test("basic", () => {
     const schema: PathItemObject = {
       get: {
+        description: "Basic GET",
         responses: {
           200: {
             description: "OK",
@@ -57,6 +58,7 @@ describe("Path Item Object", () => {
         },
       },
       post: {
+        description: "Basic POST",
         requestBody: {
           content: {
             "application/json": { $ref: 'components["schemas"]["User"]' },
@@ -70,6 +72,7 @@ describe("Path Item Object", () => {
     };
     const generated = transformPathItemObject(schema, options);
     expect(generated).toBe(`{
+  /** @description Basic GET */
   get: {
     responses: {
       /** @description OK */
@@ -92,6 +95,7 @@ describe("Path Item Object", () => {
       };
     };
   };
+  /** @description Basic POST */
   post: {
     requestBody?: {
       content: {
@@ -107,9 +111,10 @@ describe("Path Item Object", () => {
   });
 
   test("operations", () => {
-    const operations: Record<string, string> = {};
+    const operations: GlobalContext["operations"] = {};
     const schema: PathItemObject = {
       get: {
+        description: "Get a user",
         operationId: "getUser",
         responses: {
           200: {
@@ -132,10 +137,13 @@ describe("Path Item Object", () => {
     };
     const generated = transformPathItemObject(schema, { ...options, ctx: { ...options.ctx, operations } });
     expect(generated).toBe(`{
+  /** @description Get a user */
   get: operations["getUser"];
 }`);
     expect(operations).toEqual({
-      getUser: `{
+      getUser: {
+        comment: "/** @description Get a user */",
+        operationType: `{
     responses: {
       /** @description Get User */
       200: {
@@ -148,6 +156,7 @@ describe("Path Item Object", () => {
       };
     };
   }`,
+      },
     });
   });
 });

src/index.ts

@@ -22,7 +22,7 @@ describe("Paths Object", () => {
       "/api/v1/user/{user_id}": {
         parameters: [{ name: "page", in: "query", schema: { type: "number" }, description: "Page number." }],
         get: {
-          parameters: [{ name: "user_id", in: "path" }],
+          parameters: [{ name: "user_id", in: "path", description: "User ID." }],
           responses: {
             200: {
               description: "OK",
@@ -58,6 +58,7 @@ describe("Paths Object", () => {
     get: {
       parameters: {
         path: {
+          /** @description User ID. */
           user_id: string;
         };
       };
@@ -79,8 +80,8 @@ describe("Paths Object", () => {
       };
     };
     parameters: {
-        /** @description Page number. */
       query: {
+        /** @description Page number. */
         page?: number;
       };
     };