swaggie 1.3.1 → 1.4.0

package/dist/gen/genOperations.js

@@ -8,13 +8,14 @@ var _swagger = require('../swagger');
 
 
 
-
 var _utils = require('../utils');
 var _createBarrel = require('./createBarrel');
 
 
 
 
+var _jsDocs = require('./jsDocs');
+
 /**
  * Function that will analyze paths in the spec and generate the code for all the operations.
  */
@@ -121,10 +122,8 @@ function prepareClient(
       });
     }
 
-    const docs = getOperationDocs(op);
     return {
-      docs,
-      hasJSDocs: docs.length > 0 || params.length > 0,
+      jsDocs: _jsDocs.prepareJsDocsForOperation.call(void 0, op, params),
       returnType,
       responseContentType,
       method: op.method.toUpperCase(),
@@ -313,40 +312,3 @@ function getRequestBody(reqBody) {
   }
   return null;
 }
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

package/dist/gen/genTypes.js

@@ -4,6 +4,7 @@ var _swagger = require('../swagger');
 
 var _utils = require('../utils');
 var _refsHelper = require('./refsHelper');
+var _jsDocs = require('./jsDocs');
 
 /**
  * Generates TypeScript code with all the types for the given OpenAPI 3 document.
@@ -60,7 +61,7 @@ function renderSchema(
 
   const result = [];
   if (_nullishCoalesce(schema.description, () => ( schema.title))) {
-    result.push(renderComment(_nullishCoalesce(schema.description, () => ( schema.title))));
+    result.push(_jsDocs.renderComment.call(void 0, _nullishCoalesce(schema.description, () => ( schema.title))));
   }
 
   if ('x-enumNames' in schema || 'x-enum-varnames' in schema) {
@@ -197,7 +198,7 @@ function renderTypeProp(
   const type = _swagger.getTypeFromSchema.call(void 0, definition, options);
 
   if ('description' in definition || 'title' in definition) {
-    lines.push(renderComment(_nullishCoalesce(definition.description, () => ( definition.title))));
+    lines.push(_jsDocs.renderComment.call(void 0, _nullishCoalesce(definition.description, () => ( definition.title))));
   }
   const optionalMark = required ? '' : '?';
   // If prop name is not a valid identifier, we need to wrap it in quotes.
@@ -208,20 +209,6 @@ function renderTypeProp(
   return lines.join('\n');
 }
 
- function renderComment(comment) {
-  if (!comment) {
-    return null;
-  }
-
-  const commentLines = comment.split('\n');
-
-  if (commentLines.length === 1) {
-    return `/** ${comment.trim()} */`;
-  }
-
-  return ` /**\n${commentLines.map((line) => `  * ${line.trim()}`).join('\n')}\n  */`;
-} exports.renderComment = renderComment;
-
 function getMergedCompositeObjects(schema) {
   const { allOf, oneOf, anyOf, ...safeSchema } = schema;
   const composite = allOf || oneOf || anyOf || [];

package/dist/gen/jsDocs.js

@@ -0,0 +1,98 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
+
+
+/**
+ * Prepares content for the operation docs. We will use description and summary if they are defined
+ * in the spec. Additionally we will add deprecation tag if the operation is deprecated.
+ * This function should include JSDocs asterisks to make comments look nice.
+ */
+function getOperationDocs(
+  op
+) {
+  const result = [];
+  const summary = _optionalChain([op, 'access', _ => _.summary, 'optionalAccess', _2 => _2.trim, 'call', _3 => _3()]);
+  const description = _optionalChain([op, 'access', _4 => _4.description, 'optionalAccess', _5 => _5.trim, 'call', _6 => _6()]);
+  if (summary) {
+    // We want to include summary only if it's not a subset of description
+    if (!description || !description.startsWith(summary)) {
+      result.push(summary);
+    }
+  }
+  if (description) {
+    result.push(description);
+  }
+  if (op.deprecated) {
+    result.push('@deprecated');
+  }
+  return result;
+}
+
+/**
+ * Strips specific HTML tags and converts them to a simple markdown.
+ * Unknown or unclosed tags are encoded to HTML entities.
+ * @param str - The string to strip the tags from.
+ */
+function stripSpecificHtmlTags(str) {
+  // Replace specific problematic tags with better alternatives
+  return (
+    str
+      .replace(/<br\s*\/?>/gi, '\n')
+      .replace(/<\/p>/gi, '\n')
+      .replace(/<p(\s[^>]*)?>/gi, '')
+      .replace(/<b>(.*?)<\/b>/gi, '**$1**')
+      .replace(/<strong>(.*?)<\/strong>/gi, '**$1**')
+      .replace(/<i>(.*?)<\/i>/gi, '*$1*')
+      .replace(/<em>(.*?)<\/em>/gi, '*$1*')
+      .replace(/<code>(.*?)<\/code>/gi, '`$1`')
+      .replace(/<pre>(.*?)<\/pre>/gi, '`$1`')
+      // Replace h1 - h6 with markdown headers
+      .replace(
+        /<h([1-6])>(.*?)<\/h\1>/gi,
+        (match, level, content) => '#'.repeat(parseInt(level)) + ' ' + content + '\n'
+      )
+      // Replace links with markdown links
+      .replace(/<a href="([^"]+)">([^<]+)<\/a>/gi, '[$2]($1)')
+      .replace(/\n{3,}/g, '\n\n')
+      .replace(/\<=/g, '&le;')
+      .replace(/\>=/g, '&ge;')
+      .replace(/\</g, '&lt;')
+      .replace(/\>/g, '&gt;')
+      .trim()
+  );
+}
+
+ function prepareJsDocsForOperation(
+  op,
+  params
+) {
+  const docs = getOperationDocs(op);
+  if (docs.length === 0 && params.length === 0) {
+    return null;
+  }
+
+  const result = docs;
+  for (const param of params) {
+    const paramLine = `@param ${param.name} ${param.optional ? '(optional)' : ''} ${
+      param.name !== param.originalName ? `(API name: ${param.originalName})` : ''
+    }`;
+    result.push(paramLine);
+  }
+  return renderComment(result.join('\n'));
+} exports.prepareJsDocsForOperation = prepareJsDocsForOperation;
+
+ function renderComment(comment) {
+  if (!comment) {
+    return null;
+  }
+
+  const mdComment = stripSpecificHtmlTags(comment);
+  const commentLines = mdComment.split('\n');
+
+  if (commentLines.length === 1) {
+    return `/** ${mdComment.trim()} */`;
+  }
+
+  return ` /**\n${commentLines
+    .map((line) => (line.trim() === '' ? '  *' : `  * ${line.trim()}`))
+    .join('\n')}\n  */`;
+} exports.renderComment = renderComment;

package/dist/utils/utils.js

@@ -53,6 +53,20 @@ const reservedKeywords = new Set([
   'while',
   'with',
   'yield',
+
+  // Some of the variables that are used internally in the generated code. We can't allow
+  // user to use them as parameter names.
+  '$config',
+  'axios',
+  'cacheUrl',
+  'config',
+  'data',
+  'error',
+  'http',
+  'key',
+  'mutate',
+  'url',
+  'xior',
 ]);
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swaggie",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Generate TypeScript REST client code from an OpenAPI spec",
   "author": {
     "name": "Piotr Dabrowski",
@@ -60,10 +60,10 @@
   },
   "devDependencies": {
     "@types/js-yaml": "4.0.9",
-    "@types/node": "24.2.0",
+    "@types/node": "24.3.0",
     "openapi-types": "^12.1.3",
     "sucrase": "3.35.0",
-    "tsx": "^4.20.3",
+    "tsx": "^4.20.5",
     "typescript": "5.9.2"
   }
 }

package/templates/axios/operation.ejs

@@ -1,15 +1,5 @@
-<% if(it.hasJSDocs) { %>
-  /**
-<% if(it.docs && it.docs.length > 0) { %>
-   * <%~ it.docs.join('\n   * ') %>
-<% } %>
-
-<% it.parameters.forEach((parameter) => { %>
-   * @param <%= parameter.name %> <%= parameter.optional ? '(optional)' : '' %> <%= parameter.name !== parameter.originalName ? `(API name: ${parameter.originalName})` : '' %>
+<%~ it.jsDocs %>
 
-<% }); -%>
-   */
-<% } %>
   <%= it.name %>(<% it.parameters.forEach((parameter) => { %>
 <%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %> <%= parameter.optional ? (parameter.skippable ? '| null' : '| null | undefined') : '' %>,
     <% }); %>

package/templates/fetch/operation.ejs

@@ -1,15 +1,5 @@
-<% if(it.hasJSDocs) { %>
-  /**
-<% if(it.docs && it.docs.length > 0) { %>
-   * <%~ it.docs.join('\n   * ') %>
-<% } %>
-
-<% it.parameters.forEach((parameter) => { %>
-   * @param <%= parameter.name %> <%= parameter.optional ? '(optional)' : '' %> <%= parameter.name !== parameter.originalName ? `(API name: ${parameter.originalName})` : '' %>
+<%~ it.jsDocs %>
 
-<% }); -%>
-   */
-<% } %>
   <%= it.name %>(<% it.parameters.forEach((parameter) => { %>
 <%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %> <%= parameter.optional ? (parameter.skippable ? '| null' : '| null | undefined') : '' %>,
     <% }); %>

package/templates/ng1/operation.ejs

@@ -1,16 +1,5 @@
-<% if(it.hasJSDocs) { %>
-  /**
-<% if(it.docs && it.docs.length > 0) { %>
-   * <%~ it.docs.join('\n   * ') %>
-<% } %>
-
-<% it.parameters.forEach((parameter) => { %>
-   * @param <%= parameter.name %> <%= parameter.optional ? '(optional)' : '' %> <%= parameter.name !== parameter.originalName ? `(API name: ${parameter.originalName})` : '' %>
+<%~ it.jsDocs %>
 
-<% }); -%>
-   * @return Success
-   */
-<% } %>
   <%= it.name %>(<% it.parameters.forEach((parameter) => { %>
 <%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %> <%= parameter.optional ? (parameter.skippable ? '| null' : '| null | undefined') : '' %>,
     <% }); %>

package/templates/ng2/operation.ejs

@@ -1,16 +1,5 @@
-<% if(it.hasJSDocs) { %>
-  /**
-<% if(it.docs && it.docs.length > 0) { %>
-   * <%~ it.docs.join('\n   * ') %>
-<% } %>
-
-<% it.parameters.forEach((parameter) => { %>
-   * @param <%= parameter.name %> <%= parameter.optional ? '(optional)' : '' %> <%= parameter.name !== parameter.originalName ? `(API name: ${parameter.originalName})` : '' %>
+<%~ it.jsDocs %>
 
-<% }); -%>
-   * @return Success
-   */
-<% } %>
   <%= it.name %>(
     <% it.parameters.forEach((parameter) => { %>
 <%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %> <%= parameter.optional ? (parameter.skippable ? '| null' : '| null | undefined') : '' %>,

package/templates/swr-axios/operation.ejs

@@ -1,15 +1,5 @@
-<% if(it.hasJSDocs) { %>
-  /**
-<% if(it.docs && it.docs.length > 0) { %>
-   * <%~ it.docs.join('\n   * ') %>
-<% } %>
-
-<% it.parameters.forEach((parameter) => { %>
-   * @param <%= parameter.name %> <%= parameter.optional ? '(optional)' : '' %> <%= parameter.name != parameter.originalName ? `(API name: ${parameter.originalName})` : '' %>
+<%~ it.jsDocs %>
 
-<% }); -%>
-   */
-<% } %>
   <%= it.name %>(<% it.parameters.forEach((parameter) => { %>
 <%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %> <%= parameter.optional ? (parameter.skippable ? '| null' : '| null | undefined') : '' %>,
     <% }); %>

package/templates/swr-axios/swrOperation.ejs

@@ -1,15 +1,5 @@
-<% if(it.hasJSDocs) { %>
-  /**
-<% if(it.docs && it.docs.length > 0) { %>
-   * <%~ it.docs.join('\n   * ') %>
-<% } %>
-
-<% it.parameters.forEach((parameter) => { %>
-   * @param <%= parameter.name %> <%= parameter.optional ? '(optional)' : '' %> <%= parameter.name !== parameter.originalName ? `(API name: ${parameter.originalName})` : '' %>
+<%~ it.jsDocs %>
 
-<% }); -%>
-   */
-<% } %>
 export function <%= it.swrOpName %>(<% it.parameters.forEach((parameter) => { %>
   <%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %> <%= parameter.optional ? (parameter.skippable ? '| null' : '| null | undefined') : '' %>,
     <% }); %>

package/templates/tsq-xior/operation.ejs

@@ -1,15 +1,5 @@
-<% if(it.hasJSDocs) { %>
-  /**
-<% if(it.docs && it.docs.length > 0) { %>
-   * <%~ it.docs.join('\n   * ') %>
-<% } %>
-
-<% it.parameters.forEach((parameter) => { %>
-   * @param <%= parameter.name %> <%= parameter.optional ? '(optional)' : '' %> <%= parameter.name !== parameter.originalName ? `(API name: ${parameter.originalName})` : '' %>
+<%~ it.jsDocs %>
 
-<% }); -%>
-   */
-<% } %>
   <%= it.name %>(<% it.parameters.forEach((parameter) => { %>
 <%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %> <%= parameter.optional ? (parameter.skippable ? '| null' : '| null | undefined') : '' %>,
     <% }); %>

package/templates/tsq-xior/queryOperation.ejs

@@ -1,17 +1,16 @@
-<% if(it.hasJSDocs) { %>
-/**
-<% if(it.docs && it.docs.length > 0) { %>
-   * <%~ it.docs.join('\n   * ') %>
-<% } %>
-
-<% it.parameters.forEach((parameter) => { %>
-   * @param <%= parameter.name %> <%= parameter.optional ? '(optional)' : '' %> <%= parameter.name !== parameter.originalName ? `(API name: ${parameter.originalName})` : '' %>
+<%
+if (it.jsDocs) {
+  const additionalParams = `  * @param $config (optional) Additional configuration for TanStack Query
+  * @param $httpConfig (optional) Additional configuration for xior request (actually executes the request)`;
 
-<% }); -%>
-   * @param $config (optional) Additional configuration for TanStack Query
-   * @param $httpConfig (optional) Additional configuration for xior request (actually executes the request)
-   */
+  // Replace the closing */ with newline + additional params + closing */
+  const modifiedDocs = it.jsDocs.replace(/(\s*)\*\/\s*$/, `\n${additionalParams}\n */`);
+-%>
+<%~ modifiedDocs %>
+<% } else { -%>
+<%~ it.jsDocs %>
 <% } %>
+
 export function <%= it.rqOpName %><TData = <%~ it.returnType %>, TError = Error>(<% it.parameters.forEach((parameter) => { %>
   <%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %> <%= parameter.optional ? (parameter.skippable ? '| null' : '| null | undefined') : '' %>,
     <% }); %>

package/templates/xior/operation.ejs

@@ -1,15 +1,5 @@
-<% if(it.hasJSDocs) { %>
-  /**
-<% if(it.docs && it.docs.length > 0) { %>
-   * <%~ it.docs.join('\n   * ') %>
-<% } %>
-
-<% it.parameters.forEach((parameter) => { %>
-   * @param <%= parameter.name %> <%= parameter.optional ? '(optional)' : '' %> <%= parameter.name !== parameter.originalName ? `(API name: ${parameter.originalName})` : '' %>
+<%~ it.jsDocs %>
 
-<% }); -%>
-   */
-<% } %>
   <%= it.name %>(<% it.parameters.forEach((parameter) => { %>
 <%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %> <%= parameter.optional ? (parameter.skippable ? '| null' : '| null | undefined') : '' %>,
     <% }); %>