beer-swagger 1.1.1 → 4.0.2

package/generate-apis.js

@@ -2,7 +2,7 @@
 
 import fs from 'fs';
 import path from 'path';
-import { createInterface } from 'readline';
+import {createInterface} from 'readline';
 
 const ENV_PATH = path.join(process.cwd(), '.env');
 const SKIPPED_SERVICES = new Set([
@@ -116,7 +116,7 @@ function appendParamSuffix(baseName, paramSuffix) {
 }
 
 // Add a verb when the HTTP method should be reflected in the name.
-function addVerbForSingleSegment(name, method, hasPathParams = false) {
+function addVerbForSingleSegment(name, method) {
   const lower = name.toLowerCase();
   if (KEEP_METHOD_NAMES.has(lower)) {
     return name;
@@ -125,7 +125,7 @@ function addVerbForSingleSegment(name, method, hasPathParams = false) {
     const suffix = name[0].toUpperCase() + name.slice(1);
     return `removeBy${suffix}`;
   }
-  if ((method === 'post' || method === 'put') && !hasPathParams) {
+  if (method === 'post' || method === 'put') {
     return name;
   }
   const verbMap = {
@@ -166,12 +166,12 @@ function getBodyTypeName(requestBody, schemas) {
   if (!requestBody || !requestBody.content) {
     return '';
   }
-  const { content } = requestBody;
+  const {content} = requestBody;
   const firstContent = content['application/json'] || content['application/*+json'] || Object.values(content)[0];
   if (!firstContent || !firstContent.schema) {
     return '';
   }
-  const { schema } = firstContent;
+  const {schema} = firstContent;
   if (!schema.$ref) {
     return '';
   }
@@ -182,10 +182,53 @@ function getBodyTypeName(requestBody, schemas) {
   return stripped || normalized;
 }
 
+// Return the path segment immediately above the operation segment.
+function getParentPathSegment(pathStr) {
+  const segments = pathStr.split('/')
+    .filter(Boolean)
+    .filter((part) => !part.startsWith('{'));
+  return segments.length > 1 ? segments[segments.length - 2] : '';
+}
+
+// Compare two names using normalized Levenshtein similarity.
+function nameSimilarity(left, right) {
+  const a = String(left || '').replace(/[^a-zA-Z0-9]/g, '').toLowerCase();
+  const b = String(right || '').replace(/[^a-zA-Z0-9]/g, '').toLowerCase();
+  if (!a || !b) {
+    return 0;
+  }
+  if (a === b) {
+    return 1;
+  }
+  const previous = Array.from({length: b.length + 1}, (_, index) => index);
+  for (let i = 1; i <= a.length; i += 1) {
+    let diagonal = previous[0];
+    previous[0] = i;
+    for (let j = 1; j <= b.length; j += 1) {
+      const above = previous[j];
+      previous[j] = a[i - 1] === b[j - 1]
+        ? diagonal
+        : Math.min(previous[j] + 1, previous[j - 1] + 1, diagonal + 1);
+      diagonal = above;
+    }
+  }
+  return 1 - previous[b.length] / Math.max(a.length, b.length);
+}
+
+// A POST whose parent resource matches its defined request entity is a save.
+function shouldSaveByPathEntity(pathStr, method, requestBody, schemas) {
+  if (method !== 'post') {
+    return false;
+  }
+  const parentPath = getParentPathSegment(pathStr);
+  const bodyTypeName = getBodyTypeName(requestBody, schemas);
+  return !!parentPath && !!bodyTypeName && nameSimilarity(parentPath, bodyTypeName) >= 0.8;
+}
+
 // Map a Swagger schema to a runtime return type.
 function mapSchemaToType(schema, schemas, useTypes) {
   if (!schema) {
-    return '{}';
+    return 'object';
   }
   const {
     $ref,
@@ -201,18 +244,18 @@ function mapSchemaToType(schema, schemas, useTypes) {
       if (responseSchema && responseSchema.properties && responseSchema.properties.data) {
         return mapSchemaToType(responseSchema.properties.data, schemas, useTypes);
       }
-      return '{}';
+      return 'object';
     }
     const refName = normalizeDtoName(rawRefName);
     const refSchema = schemas[rawRefName] || schemas[refName];
     if (refSchema && refSchema.properties && refSchema.properties.data) {
       return mapSchemaToType(refSchema.properties.data, schemas, useTypes);
     }
-    return useTypes ? `Types.${refName}` : '{}';
+    return useTypes ? `Types.${refName}` : 'object';
   }
   if (!type && items) {
     const itemType = mapSchemaToType(items, schemas, useTypes);
-    if (itemType === '{}' || itemType === '[]') {
+    if (itemType === '[]') {
       return '[]';
     }
     return `${itemType}[]`;
@@ -234,7 +277,7 @@ function mapSchemaToType(schema, schemas, useTypes) {
   }
   if (type === 'array') {
     const itemType = mapSchemaToType(items, schemas, useTypes);
-    if (itemType === '{}' || itemType === '[]') {
+    if (itemType === '[]') {
       return '[]';
     }
     return `${itemType}[]`;
@@ -246,20 +289,20 @@ function mapSchemaToType(schema, schemas, useTypes) {
 }
 
 // Map parameter schema to a type for method signatures.
-function mapParamSchemaToType(schema, schemas, useTypes) {
+function mapParamSchemaToType(schema, schemas, useTypes, isQuery = false) {
   if (!schema) {
-    return '{}';
+    return isQuery ? 'Record<string, string | undefined>' : 'object';
   }
   const {
     $ref,
     type,
     format
   } = schema;
-  const { items } = schema;
+  const {items} = schema;
   if ($ref) {
     const refName = normalizeDtoName($ref.split('/')
       .pop());
-    return useTypes ? `Types.${refName}` : '{}';
+    return useTypes ? `Types.${refName}` : 'object';
   }
   if (!type && items) {
     return '[]';
@@ -283,26 +326,50 @@ function mapParamSchemaToType(schema, schemas, useTypes) {
     return '[]';
   }
   if (type === 'object') {
-    return 'object';
+    return isQuery ? 'Record<string, string | undefined>' : 'object';
   }
-  return 'object';
+  return isQuery ? 'Record<string, string | undefined>' : 'object';
+}
+
+// Resolve parameter type for a parameter definition.
+function resolveParamType(param, schemas) {
+  const schemaToUse = param.schema || (param.type ? {
+    type: param.type,
+    format: param.format,
+    items: param.items
+  } : null);
+  const isQuery = param.in === 'query';
+  return mapParamSchemaToType(schemaToUse, schemas, true, isQuery);
+}
+
+// Detect event streams in successful or default responses.
+function isEventStreamResponse(op) {
+  return Object.entries(op.responses || {}).some(([status, response]) => {
+    if (!/^2(?:\d{2}|XX)$/i.test(status) && status !== 'default') {
+      return false;
+    }
+    return Object.keys(response.content || {}).some((mediaType) => {
+      const type = mediaType.split(';')[0].trim().toLowerCase();
+      return type === 'text/event-stream' || type === 'event-stream';
+    });
+  });
 }
 
 // Resolve default response type from Swagger responses.
 function getDefaultReturnType(op, schemas, useTypes) {
-  const { responses = {} } = op;
+  const {responses = {}} = op;
   const res = responses['200'] || responses['201'] || responses.default || {};
-  const { content = {} } = res;
+  const {content = {}} = res;
   const firstContent = content['application/json'] || content['application/*+json'] || Object.values(content)[0];
   if (!firstContent) {
-    return '{}';
+    return 'object';
   }
   return mapSchemaToType(firstContent.schema, schemas, useTypes);
 }
 
 // Collect query/path parameters.
 function getParams(op) {
-  const { parameters = [] } = op;
+  const {parameters = []} = op;
   const params = Array.isArray(parameters) ? parameters : [];
   return params.filter((p) => p.in === 'query' || p.in === 'path');
 }
@@ -401,15 +468,28 @@ function toPascal(value) {
   return value[0].toUpperCase() + value.slice(1);
 }
 
+// Join path prefixes while keeping a single separator at their boundary.
+function joinPathPrefixes(...prefixes) {
+  return prefixes
+    .map((prefix) => typeof prefix === 'string' ? prefix.trim() : '')
+    .filter(Boolean)
+    .reduce((result, prefix) => {
+      if (!result) {
+        return prefix;
+      }
+      return `${result.replace(/\/+$/, '')}/${prefix.replace(/^\/+/, '')}`;
+    }, '');
+}
+
 // Generate API file content for a service.
-function generateForSpec(spec, serviceName, fileBase, isDefaultFetch) {
+function generateForSpec(spec, serviceName, fileBase, isDefaultFetch, responsePathPrefix = '') {
   const {
     components = {},
     tags: specTags = [],
     paths = {}
   } = spec;
-  const defaultPathPrefix = typeof spec.pathPrefix === 'string' ? spec.pathPrefix : '';
-  const { schemas = {} } = components;
+  const defaultPathPrefix = joinPathPrefixes(responsePathPrefix, spec.pathPrefix);
+  const {schemas = {}} = components;
   const tagDescriptions = {};
   if (Array.isArray(specTags)) {
     for (const tag of specTags) {
@@ -455,8 +535,8 @@ function generateForSpec(spec, serviceName, fileBase, isDefaultFetch) {
         const pathSegments = p.split('/')
           .filter(Boolean)
           .filter((part) => !part.startsWith('{'));
-        const shouldAddVerb = pathSegments.length === 1 || ((method === 'post' || method === 'put') && pathParams.length > 0);
-        name = shouldAddVerb ? addVerbForSingleSegment(inferred, method, pathParams.length > 0) : inferred;
+        const shouldAddVerb = pathSegments.length === 1;
+        name = shouldAddVerb ? addVerbForSingleSegment(inferred, method) : inferred;
       }
       if (!KEEP_METHOD_NAMES.has(name.toLowerCase())) {
         name = fixVerbCase(name);
@@ -498,6 +578,11 @@ function generateForSpec(spec, serviceName, fileBase, isDefaultFetch) {
     const className = toClassName(tag);
     const facadePrefix = toFacadePrefix(className);
     const sortedEntries = [...entries].sort((a, b) => {
+      const aDynamic = a.params.some((p) => p.in === 'path') || a.path.includes('{') ? 1 : 0;
+      const bDynamic = b.params.some((p) => p.in === 'path') || b.path.includes('{') ? 1 : 0;
+      if (aDynamic !== bDynamic) {
+        return aDynamic - bDynamic;
+      }
       const aScore = (a.hasBody ? 1 : 0) + (a.params.length ? 1 : 0);
       const bScore = (b.hasBody ? 1 : 0) + (b.params.length ? 1 : 0);
       return aScore - bScore;
@@ -518,21 +603,33 @@ function generateForSpec(spec, serviceName, fileBase, isDefaultFetch) {
       if (!KEEP_METHOD_NAMES.has(name.toLowerCase()) && (name === 'get' || name === 'delete') && facadePrefix) {
         name = `${name}${facadePrefix}`;
       }
+      const isDynamicPath = entryParams.some((p) => p.in === 'path') || entryPath.includes('{');
+      const saveByPathEntity = shouldSaveByPathEntity(
+        entryPath,
+        entryMethod,
+        entryHasBody ? entryOp.requestBody : null,
+        schemas
+      );
+      if (saveByPathEntity || (seen.has(name) && isDynamicPath && (entryMethod === 'post' || entryMethod === 'put'))) {
+        const hasSavePrefix = name.startsWith('save') && (name.length === 4 || /^[A-Z]/.test(name.slice(4)));
+        name = hasSavePrefix ? name : `save${toPascal(name)}`;
+      }
+      const baseName = name;
       if (seen.has(name)) {
         const bodyTypeName = entryHasBody ? getBodyTypeName(entryOp.requestBody, schemas) : '';
         if (bodyTypeName) {
-          name = `${entryName}By${toPascal(bodyTypeName)}`;
+          name = `${baseName}By${toPascal(bodyTypeName)}`;
         }
       }
       if (seen.has(name)) {
         const paramSuffix = toParamSuffix(entryParams, paramNameMap);
         if (paramSuffix) {
-          name = appendParamSuffix(entryName, paramSuffix);
+          name = appendParamSuffix(baseName, paramSuffix);
         }
       }
       if (seen.has(name)) {
         const methodSuffix = entryMethod[0].toUpperCase() + entryMethod.slice(1);
-        name = `${entryName}${methodSuffix}`;
+        name = `${baseName}${methodSuffix}`;
       }
       seen.add(name);
       const defaultType = entryDefaultReturnType;
@@ -543,20 +640,19 @@ function generateForSpec(spec, serviceName, fileBase, isDefaultFetch) {
 
       const paramArgs = orderedParams.map((p) => {
         const {
-          schema: paramSchema,
           required,
           name: paramName
         } = p;
         const mappedName = paramNameMap.get(paramName) || paramName;
-        const paramType = mapParamSchemaToType(paramSchema, schemas, true);
+        const paramType = resolveParamType(p, schemas);
         const optional = required ? '' : '?';
         return `${mappedName}${optional}: ${paramType}`;
       });
 
-      let bodyType = '{}';
-      const { requestBody: opRequestBody } = entryOp;
+      let bodyType = 'object';
+      const {requestBody: opRequestBody} = entryOp;
       if (entryHasBody && opRequestBody && opRequestBody.content) {
-        const { content } = opRequestBody;
+        const {content} = opRequestBody;
         const firstContent = content['application/json'] || content['application/*+json'] || Object.values(content)[0];
         if (firstContent && firstContent.schema) {
           bodyType = mapSchemaToType(firstContent.schema, schemas, true);
@@ -605,17 +701,43 @@ function generateForSpec(spec, serviceName, fileBase, isDefaultFetch) {
         methods.push('   */');
       }
 
-      const queryParamNames = entryParams.filter((p) => p.in === 'query')
-        .map((p) => {
+      const queryParams = entryParams.filter((p) => p.in === 'query');
+      let paramsObject = 'undefined';
+      if (queryParams.length === 1) {
+        const p = queryParams[0];
+        const paramType = resolveParamType(p, schemas);
+        const mappedName = paramNameMap.get(p.name) || p.name;
+        if (paramType === 'Record<string, string | undefined>') {
+          paramsObject = mappedName;
+        } else {
+          const key = formatObjectKey(p.name);
+          const prop = mappedName === p.name ? key : `${key}: ${mappedName}`;
+          paramsObject = `{ ${prop} }`;
+        }
+      } else if (queryParams.length > 1) {
+        const entries = queryParams.map((p) => {
+          const paramType = resolveParamType(p, schemas);
           const mappedName = paramNameMap.get(p.name) || p.name;
+          if (paramType === 'Record<string, string | undefined>') {
+            return `...${mappedName}`;
+          }
           const key = formatObjectKey(p.name);
           return mappedName === p.name ? key : `${key}: ${mappedName}`;
         });
-      const paramsObject = queryParamNames.length ? `{ ${queryParamNames.join(', ')} }` : 'undefined';
+        paramsObject = `{ ${entries.join(', ')} }`;
+      }
 
       const pathTemplate = withPathParams(entryPath, entryParams, paramNameMap);
       const pathLiteral = pathTemplate.includes('${') ? `\`${pathTemplate}\`` : `'${pathTemplate}'`;
 
+      if (isEventStreamResponse(entryOp)) {
+        methods.push(`  public ${name}(${sigParts}): EventSource {`);
+        methods.push(`    return this.sse(${pathLiteral}, ${paramsObject});`);
+        methods.push('  }');
+        methods.push('');
+        continue;
+      }
+
       if (entryMethod === 'get') {
         methods.push(`  public async ${name}<T = ${defaultType}>(${sigParts}): Promise<JsonResponse<T>> {`);
         methods.push(`    return await this.get<T>(${pathLiteral}, ${paramsObject});`);
@@ -733,7 +855,7 @@ function generateForSpec(spec, serviceName, fileBase, isDefaultFetch) {
 // Map Swagger schema to a TS type for DTO output.
 function mapSchemaToTsType(schema, schemas) {
   if (!schema) {
-    return '{}';
+    return 'object';
   }
   const {
     $ref,
@@ -751,7 +873,7 @@ function mapSchemaToTsType(schema, schemas) {
       if (refSchema && refSchema.properties && refSchema.properties.data) {
         return mapSchemaToTsType(refSchema.properties.data, schemas);
       }
-      return '{}';
+      return 'object';
     }
     return normalizeDtoName(refName);
   }
@@ -763,6 +885,9 @@ function mapSchemaToTsType(schema, schemas) {
     return schemaEnum.map((v) => (typeof v === 'string' ? `'${v}'` : String(v)))
       .join(' | ');
   }
+  if (type === 'any') {
+    return 'any';
+  }
   if (type === 'string') {
     return 'string';
   }
@@ -784,17 +909,44 @@ function mapSchemaToTsType(schema, schemas) {
   }
   if (type === 'object') {
     if (additionalProperties) {
-      return 'Record<string, {}>';
+      return 'Record<string, object>';
     }
-    return '{}';
+    return 'object';
   }
-  return '{}';
+  return 'object';
+}
+
+// Swagger treats schemas without a type constraint as any.
+function isAnySchema(schema) {
+  if (schema === true || schema === null || schema === undefined) {
+    return true;
+  }
+  if (typeof schema !== 'object' || Array.isArray(schema)) {
+    return false;
+  }
+  if (schema.type === 'any') {
+    return true;
+  }
+  const typeConstraints = [
+    '$ref',
+    'type',
+    'items',
+    'enum',
+    'const',
+    'properties',
+    'additionalProperties',
+    'allOf',
+    'oneOf',
+    'anyOf',
+    'not'
+  ];
+  return !typeConstraints.some((key) => schema[key] !== undefined);
 }
 
 // Generate DTO/type definitions file content.
 function generateTypes(spec) {
-  const { components = {} } = spec;
-  const { schemas = {} } = components;
+  const {components = {}} = spec;
+  const {schemas = {}} = components;
   const lines = [];
   lines.push('/*');
   lines.push(' * This file is auto-generated. Do not edit manually.');
@@ -829,9 +981,16 @@ function generateTypes(spec) {
       const def = typeDefs.get(normalizedName);
       const requiredSet = new Set(required || []);
       for (const [prop, propSchema] of Object.entries(properties)) {
-        def.props[prop] = mapSchemaToTsType(propSchema, schemas);
+        if (isAnySchema(propSchema)) {
+          continue;
+        }
+        const propType = mapSchemaToTsType(propSchema, schemas);
+        if (propType === 'any') {
+          continue;
+        }
+        def.props[prop] = propType;
         def.required[prop] = requiredSet.has(prop);
-        const { description } = propSchema || {};
+        const {description} = propSchema || {};
         const desc = description
           ? description.replace(/\n/g, ' ')
             .trim()
@@ -883,6 +1042,26 @@ async function fetchJson(url) {
   return response.json();
 }
 
+// Fetch JSON together with response headers needed by API generation.
+async function fetchJsonWithHeaders(url) {
+  console.log(`Fetching ${url}`);
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${url}: ${response.status}`);
+  }
+  const responseText = await response.text();
+  if (responseText === '') {
+    return {
+      data: {},
+      pathPrefix: response.headers.get('x-path-prefix') || ''
+    };
+  }
+  return {
+    data: JSON.parse(responseText),
+    pathPrefix: response.headers.get('x-path-prefix') || ''
+  };
+}
+
 // Read key/value pairs from .env without extra dependencies.
 function readEnvFile() {
   if (!fs.existsSync(ENV_PATH)) {
@@ -911,7 +1090,7 @@ function readEnvFile() {
 // Persist values into .env (overwrite or append keys).
 function writeEnvFile(nextEnv) {
   const existing = readEnvFile();
-  const merged = { ...existing, ...nextEnv };
+  const merged = {...existing, ...nextEnv};
   const lines = Object.entries(merged)
     .map(([key, value]) => `${key}=${value}`);
   fs.writeFileSync(ENV_PATH, `${lines.join('\n')}\n`, 'utf8');
@@ -946,7 +1125,7 @@ async function promptForMissing(env) {
     rl.question(q, resolve);
   });
 
-  const result = { ...env };
+  const result = {...env};
   if (!result.SWAGGER_BASE_URL) {
     result.SWAGGER_BASE_URL = (await ask('BASE_URL: ')).trim();
   }
@@ -970,7 +1149,7 @@ async function main() {
     SWAGGER_BASE_URL: baseUrl,
     SWAGGER_OUT_DIRECTORY: directory,
     IS_DEFAULT_FETCH: isDefaultFetch
-  } = { ...process.env, ...envFile };
+  } = {...process.env, ...envFile};
   isDefaultFetch = normalizeBoolean(isDefaultFetch);
 
   if (!baseUrl || !directory || isDefaultFetch === undefined) {
@@ -1015,10 +1194,10 @@ async function main() {
   }
 
   if (!fs.existsSync(outputDirectory)) {
-    fs.mkdirSync(outputDirectory, { recursive: true });
+    fs.mkdirSync(outputDirectory, {recursive: true});
   }
   if (!fs.existsSync(typesDirectory)) {
-    fs.mkdirSync(typesDirectory, { recursive: true });
+    fs.mkdirSync(typesDirectory, {recursive: true});
   }
 
   for (const service of services) {
@@ -1033,9 +1212,9 @@ async function main() {
       continue;
     }
     const specUrl = `${baseUrl}${url}`;
-    const spec = await fetchJson(specUrl);
+    const {data: spec, pathPrefix} = await fetchJsonWithHeaders(specUrl);
     const fileBase = toFileBase(serviceName);
-    const content = generateForSpec(spec, serviceName, fileBase, isDefaultFetch);
+    const content = generateForSpec(spec, serviceName, fileBase, isDefaultFetch, pathPrefix);
     const typesContent = generateTypes(spec);
 
     const outPath = path.join(outputDirectory, `${fileBase}.ts`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beer-swagger",
-  "version": "1.1.1",
+  "version": "4.0.2",
   "bin": {
     "beer-swagger": "./generate-apis.js"
   },