add return description to operations

Author: William Duncan

gen/Schema.ts

@@ -31,6 +31,7 @@ namespace Schema {
         export interface Response {
             status: number;
             type: Schema.Type;
+            description?: string;
         }
 
         export interface Namespace {

gen/docs.ts

@@ -1,6 +1,6 @@
 import Schema from "./Schema";
 import {Config} from "./Config";
-import {getReturnType, getThrows, replaceModelTypes} from "./util.js";
+import {getReturnDescription, getReturnType, getThrows, replaceModelTypes} from "./util.js";
 import DocSchema from "./DocSchema.js";
 import fs from "node:fs/promises";
 import Package from "./Package";
@@ -63,7 +63,7 @@ export function generateDocSchema (schema: Schema, config: Config, pkg: Package)
     }
     // make operations into methods
     const operationMethods = operations.map(operation => {
-        const returns = {type: getReturnType(operation, schema, config)};
+        const returns = {type: getReturnType(operation, schema, config), description: getReturnDescription(operation, schema, config)};
         const throws = getThrows(operation, schema, config).map(type => ({type}));
         const pathParams = Object.entries(operation.parameters.path ?? {}).map(([name, parameter]) => new DocSchema.Parameter(name, parameter.type, parameter.description, parameter.required, parameter.default));
         const queryParams = Object.entries(operation.parameters.query ?? {}).map(([name, parameter]) => new DocSchema.Parameter(name, parameter.type, parameter.description, parameter.required, parameter.default));

gen/source.ts

@@ -3,12 +3,13 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import Mustache from "mustache";
 import {Config} from "./Config";
-import {getReturnType, getThrows, replaceModelTypes} from "./util.js";
+import {getReturnDescription, getReturnType, getThrows, replaceModelTypes} from "./util.js";
 import Package from "./Package";
 
 interface FlatOperation {
     name: string;
     returnType: string;
+    returnDescription?: string;
     params: {
         path: string;
         query: string;
@@ -43,6 +44,7 @@ export default async (schema: Schema, config: Config, pkg: Package) => {
         const operations: FlatOperation[] = [];
         for (const [name, operation] of input) {
             const returnType = getReturnType(operation, schema, config);
+            const returnDescription = getReturnDescription(operation, schema, config);
             const toFlatParam = ([name, parameter]: [string, Schema.Operation.Parameter]): NamedParameter => {
                 const ts = `${name}${!parameter.required && !parameter.default ? "?: " : ": "}${parameter.type}${parameter.default ? ` = ${parameter.default}` : ""}`;
                 return {name, ts, ...parameter};
@@ -68,6 +70,7 @@ export default async (schema: Schema, config: Config, pkg: Package) => {
             operations.push({
                 name,
                 returnType,
+                returnDescription,
                 params,
                 allParams,
                 tsArgs,

gen/templates/main.mustache

@@ -206,6 +206,9 @@ class {{config.name}} {
          * @throws {<%& . %>}
          <%={{ }}=%>
          {{/throws}}
+         {{#returnDescription}}
+         * @returns {{{returnDescription}}}
+         {{/returnDescription}}
          */
          {{name}}: async ({{{tsArgs}}}): Promise<{{config.name}}.ApiResponse<{{{returnType}}}>> => {
             return await this.#sendRequest<{{{returnType}}}>({{{operation}}}, {{{params.path}}}, {{{params.query}}}, {{{params.body}}});
@@ -226,6 +229,9 @@ class {{config.name}} {
      * @throws {<%& . %>}
      <%={{ }}=%>
      {{/throws}}
+     {{#returnDescription}}
+     * @returns {{{returnDescription}}}
+     {{/returnDescription}}
      */
      public async {{name}}({{{tsArgs}}}): Promise<{{config.name}}.ApiResponse<{{{returnType}}}>> {
         return await this.#sendRequest<{{{returnType}}}>({{{operation}}}, {{{params.path}}}, {{{params.query}}}, {{{params.body}}});

gen/util.ts

@@ -12,6 +12,17 @@ export function getReturnType(operation: Schema.Operation, schema: Schema, confi
     return operation.returns.filter(r => r.status >= 200 && r.status < 300).map(r => r.type.endsWith("[]") ? `${config.name}.PaginatedData<${schema.models.find(m => m.name === r.type.slice(0, -2)) ? `${config.name}.${r.type}` : r.type}>` : schema.models.find(m => m.name === r.type) ? `${config.name}.${r.type}` : r.type).join(" | ");
 }
 
+/**
+ * Get return description of operation
+ * @param operation
+ * @param schema
+ * @param config
+ * @returns The combined return description
+ */
+export function getReturnDescription(operation: Schema.Operation, schema: Schema, config: Config): string {
+    return operation.returns.filter(r => r.status >= 200 && r.status < 300 && r.description).map(r => r.description).join(" ");
+}
+
 /**
  * Get types the operation throws
  * @param operation