JSDoc for every type and interface of the generated Integration

example/example.client.ts

@@ -5,11 +5,13 @@ type Type1 = {
 
 type SomeOf<T> = T[keyof T];
 
+/** get /v1/user/retrieve */
 type GetV1UserRetrieveInput = {
   /** a numeric string containing the id of the user */
   id: string;
 };
 
+/** get /v1/user/retrieve */
 type GetV1UserRetrievePositiveVariant1 = {
   status: "success";
   data: {
@@ -22,45 +24,55 @@ type GetV1UserRetrievePositiveVariant1 = {
   };
 };
 
+/** get /v1/user/retrieve */
 interface GetV1UserRetrievePositiveResponseVariants {
   200: GetV1UserRetrievePositiveVariant1;
 }
 
+/** get /v1/user/retrieve */
 type GetV1UserRetrieveNegativeVariant1 = {
   status: "error";
   error: {
     message: string;
   };
 };
 
+/** get /v1/user/retrieve */
 interface GetV1UserRetrieveNegativeResponseVariants {
   400: GetV1UserRetrieveNegativeVariant1;
 }
 
+/** delete /v1/user/:id/remove */
 type DeleteV1UserIdRemoveInput = {
   /** numeric string */
   id: string;
 };
 
+/** delete /v1/user/:id/remove */
 type DeleteV1UserIdRemovePositiveVariant1 = undefined;
 
+/** delete /v1/user/:id/remove */
 interface DeleteV1UserIdRemovePositiveResponseVariants {
   204: DeleteV1UserIdRemovePositiveVariant1;
 }
 
+/** delete /v1/user/:id/remove */
 type DeleteV1UserIdRemoveNegativeVariant1 = undefined;
 
+/** delete /v1/user/:id/remove */
 interface DeleteV1UserIdRemoveNegativeResponseVariants {
   404: DeleteV1UserIdRemoveNegativeVariant1;
 }
 
+/** patch /v1/user/:id */
 type PatchV1UserIdInput = {
   key: string;
   id: string;
   name: string;
   birthday: string;
 };
 
+/** patch /v1/user/:id */
 type PatchV1UserIdPositiveVariant1 = {
   status: "success";
   data: {
@@ -69,105 +81,131 @@ type PatchV1UserIdPositiveVariant1 = {
   };
 };
 
+/** patch /v1/user/:id */
 interface PatchV1UserIdPositiveResponseVariants {
   200: PatchV1UserIdPositiveVariant1;
 }
 
+/** patch /v1/user/:id */
 type PatchV1UserIdNegativeVariant1 = {
   status: "error";
   error: {
     message: string;
   };
 };
 
+/** patch /v1/user/:id */
 interface PatchV1UserIdNegativeResponseVariants {
   400: PatchV1UserIdNegativeVariant1;
 }
 
+/** post /v1/user/create */
 type PostV1UserCreateInput = {
   name: string;
 };
 
+/** post /v1/user/create */
 type PostV1UserCreatePositiveVariant1 = {
   status: "created";
   data: {
     id: number;
   };
 };
 
+/** post /v1/user/create */
 interface PostV1UserCreatePositiveResponseVariants {
   201: PostV1UserCreatePositiveVariant1;
   202: PostV1UserCreatePositiveVariant1;
 }
 
+/** post /v1/user/create */
 type PostV1UserCreateNegativeVariant1 = {
   status: "exists";
   id: number;
 };
 
+/** post /v1/user/create */
 type PostV1UserCreateNegativeVariant2 = {
   status: "error";
   reason: string;
 };
 
+/** post /v1/user/create */
 interface PostV1UserCreateNegativeResponseVariants {
   409: PostV1UserCreateNegativeVariant1;
   400: PostV1UserCreateNegativeVariant2;
   500: PostV1UserCreateNegativeVariant2;
 }
 
+/** get /v1/user/list */
 type GetV1UserListInput = {};
 
+/** get /v1/user/list */
 type GetV1UserListPositiveVariant1 = {
   name: string;
 }[];
 
+/** get /v1/user/list */
 interface GetV1UserListPositiveResponseVariants {
   200: GetV1UserListPositiveVariant1;
 }
 
+/** get /v1/user/list */
 type GetV1UserListNegativeVariant1 = string;
 
+/** get /v1/user/list */
 interface GetV1UserListNegativeResponseVariants {
   400: GetV1UserListNegativeVariant1;
 }
 
+/** get /v1/avatar/send */
 type GetV1AvatarSendInput = {
   userId: string;
 };
 
+/** get /v1/avatar/send */
 type GetV1AvatarSendPositiveVariant1 = string;
 
+/** get /v1/avatar/send */
 interface GetV1AvatarSendPositiveResponseVariants {
   200: GetV1AvatarSendPositiveVariant1;
 }
 
+/** get /v1/avatar/send */
 type GetV1AvatarSendNegativeVariant1 = string;
 
+/** get /v1/avatar/send */
 interface GetV1AvatarSendNegativeResponseVariants {
   400: GetV1AvatarSendNegativeVariant1;
 }
 
+/** get /v1/avatar/stream */
 type GetV1AvatarStreamInput = {
   userId: string;
 };
 
+/** get /v1/avatar/stream */
 type GetV1AvatarStreamPositiveVariant1 = Buffer;
 
+/** get /v1/avatar/stream */
 interface GetV1AvatarStreamPositiveResponseVariants {
   200: GetV1AvatarStreamPositiveVariant1;
 }
 
+/** get /v1/avatar/stream */
 type GetV1AvatarStreamNegativeVariant1 = string;
 
+/** get /v1/avatar/stream */
 interface GetV1AvatarStreamNegativeResponseVariants {
   400: GetV1AvatarStreamNegativeVariant1;
 }
 
+/** post /v1/avatar/upload */
 type PostV1AvatarUploadInput = {
   avatar: any;
 };
 
+/** post /v1/avatar/upload */
 type PostV1AvatarUploadPositiveVariant1 = {
   status: "success";
   data: {
@@ -179,62 +217,75 @@ type PostV1AvatarUploadPositiveVariant1 = {
   };
 };
 
+/** post /v1/avatar/upload */
 interface PostV1AvatarUploadPositiveResponseVariants {
   200: PostV1AvatarUploadPositiveVariant1;
 }
 
+/** post /v1/avatar/upload */
 type PostV1AvatarUploadNegativeVariant1 = {
   status: "error";
   error: {
     message: string;
   };
 };
 
+/** post /v1/avatar/upload */
 interface PostV1AvatarUploadNegativeResponseVariants {
   400: PostV1AvatarUploadNegativeVariant1;
 }
 
+/** post /v1/avatar/raw */
 type PostV1AvatarRawInput = Buffer;
 
+/** post /v1/avatar/raw */
 type PostV1AvatarRawPositiveVariant1 = {
   status: "success";
   data: {
     length: number;
   };
 };
 
+/** post /v1/avatar/raw */
 interface PostV1AvatarRawPositiveResponseVariants {
   200: PostV1AvatarRawPositiveVariant1;
 }
 
+/** post /v1/avatar/raw */
 type PostV1AvatarRawNegativeVariant1 = {
   status: "error";
   error: {
     message: string;
   };
 };
 
+/** post /v1/avatar/raw */
 interface PostV1AvatarRawNegativeResponseVariants {
   400: PostV1AvatarRawNegativeVariant1;
 }
 
+/** get /v1/events/time */
 type GetV1EventsTimeInput = {
   trigger?: string | undefined;
 };
 
+/** get /v1/events/time */
 type GetV1EventsTimePositiveVariant1 = {
   data: number;
   event: "time";
   id?: string | undefined;
   retry?: number | undefined;
 };
 
+/** get /v1/events/time */
 interface GetV1EventsTimePositiveResponseVariants {
   200: GetV1EventsTimePositiveVariant1;
 }
 
+/** get /v1/events/time */
 type GetV1EventsTimeNegativeVariant1 = string;
 
+/** get /v1/events/time */
 interface GetV1EventsTimeNegativeResponseVariants {
   400: GetV1EventsTimeNegativeVariant1;
 }

src/integration-helpers.ts

@@ -198,15 +198,17 @@ export const makePromise = (subject: ts.TypeNode | "any") =>
 export const makeInterface = (
   name: ts.Identifier | string,
   props: ts.PropertySignature[],
-  { isPublic }: { isPublic?: boolean } = {},
-) =>
-  f.createInterfaceDeclaration(
+  { isPublic, comment }: { isPublic?: boolean; comment?: string } = {},
+) => {
+  const node = f.createInterfaceDeclaration(
     isPublic ? exportModifier : undefined,
     name,
     undefined,
     undefined,
     props,
   );
+  return comment ? addJsDocComment(node, comment) : node;
+};
 
 export const makeTypeParams = (
   params: Partial<Record<string, ts.Identifier>>,

src/integration.ts

@@ -194,9 +194,11 @@ export class Integration {
     const ctxOut = { brandHandling, ctx: { ...commons, isResponse: true } };
     const onEndpoint: OnEndpoint = (endpoint, path, method) => {
       const entitle = makeCleanId.bind(null, method, path); // clean id with method+path prefix
+      const request = `${method} ${path}`;
       const input = makeType(
         entitle("input"),
         zodToTs(endpoint.getSchema("input"), ctxIn),
+        { comment: request },
       );
       this.program.push(input);
       const dictionaries = responseVariants.reduce(
@@ -206,6 +208,7 @@ export class Integration {
             const variantType = makeType(
               entitle(responseVariant, "variant", `${idx + 1}`),
               zodToTs(mimeTypes ? schema : noContent, ctxOut),
+              { comment: request },
             );
             this.program.push(variantType);
             return statusCodes.map((code) =>
@@ -218,6 +221,7 @@ export class Integration {
           const dict = makeInterface(
             entitle(responseVariant, "response", "variants"),
             props,
+            { comment: request },
           );
           this.program.push(dict);
           return Object.assign(agg, { [responseVariant]: dict });
@@ -228,7 +232,6 @@ export class Integration {
       const isJson = endpoint
         .getResponses("positive")
         .some(({ mimeTypes }) => mimeTypes?.includes(contentTypes.json));
-      const request = `${method} ${path}`;
       const literalIdx = f.createLiteralTypeNode(
         f.createStringLiteral(request),
       );