Merge pull request #439 from hey-api/feat/jsdoc-comments-for-options

fix: add jsdoc comments with use options

.changeset/shaggy-eggs-count.md

@@ -0,0 +1,5 @@
+---
+"@hey-api/openapi-ts": patch
+---
+
+fix: add jsdoc comments with use options

packages/openapi-ts/src/utils/write/services.ts

@@ -73,11 +73,21 @@ const toOperationReturnType = (operation: Operation) => {
 const toOperationComment = (operation: Operation) => {
   const config = getConfig();
   let params: string[] = [];
-  if (!config.useOptions && operation.parameters.length) {
-    params = operation.parameters.map(
-      (p) =>
-        `@param ${p.name} ${p.description ? escapeComment(p.description) : ''}`,
-    );
+  if (operation.parameters.length) {
+    if (config.useOptions) {
+      params = [
+        '@param data The data for the request.',
+        ...operation.parameters.map(
+          (p) =>
+            `@param data.${p.name} ${p.description ? escapeComment(p.description) : ''}`,
+        ),
+      ];
+    } else {
+      params = operation.parameters.map(
+        (p) =>
+          `@param ${p.name} ${p.description ? escapeComment(p.description) : ''}`,
+      );
+    }
   }
   const comment = [
     operation.deprecated && '@deprecated',

packages/openapi-ts/test/__snapshots__/test/generated/v2/services.gen.ts.snap

@@ -91,6 +91,16 @@ export class SimpleService {
 
 export class DescriptionsService {
   /**
+   * @param data The data for the request.
+   * @param data.parameterWithBreaks Testing multiline comments in string: First line
+   * Second line
+   *
+   * Fourth line
+   * @param data.parameterWithBackticks Testing backticks in string: `backticks` and ```multiple backticks``` should work
+   * @param data.parameterWithSlashes Testing slashes in string: \backwards\\\ and /forwards/// should work
+   * @param data.parameterWithExpressionPlaceholders Testing expression placeholders in string: ${expression} should work
+   * @param data.parameterWithQuotes Testing quotes in string: 'single quote''' and "double quotes""" should work
+   * @param data.parameterWithReservedCharacters Testing reserved characters in string: * inline * and ** inline ** should work
    * @throws ApiError
    */
   public static callWithDescriptions(
@@ -121,6 +131,12 @@ export class DescriptionsService {
 
 export class ParametersService {
   /**
+   * @param data The data for the request.
+   * @param data.parameterHeader This is the parameter that goes into the header
+   * @param data.parameterQuery This is the parameter that goes into the query params
+   * @param data.parameterForm This is the parameter that goes into the form data
+   * @param data.parameterBody This is the parameter that is sent as request body
+   * @param data.parameterPath This is the parameter that goes into the path
    * @throws ApiError
    */
   public static callWithParameters(
@@ -153,6 +169,15 @@ export class ParametersService {
   }
 
   /**
+   * @param data The data for the request.
+   * @param data.parameterHeader This is the parameter that goes into the request header
+   * @param data.parameterQuery This is the parameter that goes into the request query params
+   * @param data.parameterForm This is the parameter that goes into the request form data
+   * @param data.parameterBody This is the parameter that is sent as request body
+   * @param data.parameterPath1 This is the parameter that goes into the path
+   * @param data.parameterPath2 This is the parameter that goes into the path
+   * @param data.parameterPath3 This is the parameter that goes into the path
+   * @param data._default This is the parameter with a reserved keyword
    * @throws ApiError
    */
   public static callWithWeirdParameterNames(
@@ -193,6 +218,12 @@ export class ParametersService {
 
 export class DefaultsService {
   /**
+   * @param data The data for the request.
+   * @param data.parameterString This is a simple string with default value
+   * @param data.parameterNumber This is a simple number with default value
+   * @param data.parameterBoolean This is a simple boolean with default value
+   * @param data.parameterEnum This is a simple enum with default value
+   * @param data.parameterModel This is a simple model with default value
    * @throws ApiError
    */
   public static callWithDefaultParameters(
@@ -219,6 +250,12 @@ export class DefaultsService {
   }
 
   /**
+   * @param data The data for the request.
+   * @param data.parameterString This is a simple string that is optional with default value
+   * @param data.parameterNumber This is a simple number that is optional with default value
+   * @param data.parameterBoolean This is a simple boolean that is optional with default value
+   * @param data.parameterEnum This is a simple enum that is optional with default value
+   * @param data.parameterModel This is a simple model that is optional with default value
    * @throws ApiError
    */
   public static callWithDefaultOptionalParameters(
@@ -245,6 +282,15 @@ export class DefaultsService {
   }
 
   /**
+   * @param data The data for the request.
+   * @param data.parameterStringWithNoDefault This is a string with no default
+   * @param data.parameterOptionalStringWithDefault This is a optional string with default
+   * @param data.parameterOptionalStringWithEmptyDefault This is a optional string with empty default
+   * @param data.parameterOptionalStringWithNoDefault This is a optional string with no default
+   * @param data.parameterStringWithDefault This is a string with default
+   * @param data.parameterStringWithEmptyDefault This is a string with empty default
+   * @param data.parameterStringNullableWithNoDefault This is a string that can be null with no default
+   * @param data.parameterStringNullableWithDefault This is a string that can be null with default
    * @throws ApiError
    */
   public static callToTestOrderOfParams(
@@ -494,6 +540,12 @@ export class MultipleTags3Service {
 
 export class CollectionFormatService {
   /**
+   * @param data The data for the request.
+   * @param data.parameterArrayCsv This is an array parameter that is sent as csv format (comma-separated values)
+   * @param data.parameterArraySsv This is an array parameter that is sent as ssv format (space-separated values)
+   * @param data.parameterArrayTsv This is an array parameter that is sent as tsv format (tab-separated values)
+   * @param data.parameterArrayPipes This is an array parameter that is sent as pipes format (pipe-separated values)
+   * @param data.parameterArrayMulti This is an array parameter that is sent as multi format (multiple parameter instances)
    * @throws ApiError
    */
   public static collectionFormat(
@@ -522,6 +574,15 @@ export class CollectionFormatService {
 
 export class TypesService {
   /**
+   * @param data The data for the request.
+   * @param data.parameterArray This is an array parameter
+   * @param data.parameterDictionary This is a dictionary parameter
+   * @param data.parameterEnum This is an enum parameter
+   * @param data.parameterNumber This is a number parameter
+   * @param data.parameterString This is a string parameter
+   * @param data.parameterBoolean This is a boolean parameter
+   * @param data.parameterObject This is an object parameter
+   * @param data.id This is a number parameter
    * @returns number Response is a simple number
    * @returns string Response is a simple string
    * @returns boolean Response is a simple boolean
@@ -567,6 +628,9 @@ export class TypesService {
 
 export class ComplexService {
   /**
+   * @param data The data for the request.
+   * @param data.parameterObject Parameter containing object
+   * @param data.parameterReference Parameter containing reference
    * @returns ModelWithString Successful response
    * @throws ApiError
    */
@@ -613,6 +677,8 @@ export class HeaderService {
 
 export class ErrorService {
   /**
+   * @param data The data for the request.
+   * @param data.status Status code to return
    * @returns unknown Custom message: Successful response
    * @throws ApiError
    */
@@ -640,6 +706,8 @@ export class ErrorService {
 
 export class NonAsciiÆøåÆøÅöôêÊService {
   /**
+   * @param data The data for the request.
+   * @param data.nonAsciiParamæøåÆøÅöôêÊ Dummy input param
    * @returns NonAsciiStringæøåÆØÅöôêÊ字符串 Successful response
    * @throws ApiError
    */