@open-mercato/shared 0.9.1-develop.7476.1.342138d35e → 0.9.1-develop.7496.1.3346415f94

package/dist/lib/openapi/generator.js

@@ -59,6 +59,19 @@ function normalizePath(path) {
   }).join("/");
   return { path: "/" + normalized, params };
 }
+function expandOptionalPathParams(normalized) {
+  const required = normalized.params.filter((param) => !param.optional);
+  const optionalParam = normalized.params.find((param) => param.optional);
+  const fullVariant = {
+    path: normalized.path,
+    params: normalized.params.map((param) => ({ ...param, optional: false }))
+  };
+  if (!optionalParam) return [fullVariant];
+  const placeholder = `/{${optionalParam.name}}`;
+  if (!normalized.path.endsWith(placeholder)) return [fullVariant];
+  const basePath = normalized.path.slice(0, -placeholder.length) || "/";
+  return [fullVariant, { path: basePath, params: required, omittedParam: optionalParam.name }];
+}
 function unwrap(schema) {
   if (!schema) {
     return { schema: void 0, optional: true, nullable: false };
@@ -564,14 +577,14 @@ function buildParameters(schema, location, pathParamNames) {
   const params = [];
   if (location === "path" && pathParamNames && pathParamNames.length) {
     const merged = mergePathParamSchemas(schema, pathParamNames);
-    for (const { name, schema: paramSchema, optional } of merged) {
+    for (const { name, schema: paramSchema } of merged) {
       const jsonSchema = zodToJsonSchema(paramSchema);
       const example = generateExample(paramSchema);
       const description = extractZodDescription(paramSchema);
       params.push({
         name,
         in: "path",
-        required: !optional,
+        required: true,
         schema: jsonSchema ?? { type: "string" },
         example,
         ...description ? { description } : {}
@@ -631,8 +644,7 @@ function mergePathParamSchemas(schema, params) {
   for (const param of params) {
     merged.push({
       name: param.name,
-      schema: map[param.name],
-      optional: !!param.optional
+      schema: map[param.name]
     });
   }
   return merged;
@@ -883,6 +895,7 @@ function buildOpenApiDocument(modules, options = {}) {
   ensureSecurityComponents(doc);
   const includeAccessControlMetadata = options.includeAccessControlMetadata !== false;
   const tags = /* @__PURE__ */ new Map();
+  const derivedOperations = /* @__PURE__ */ new Set();
   for (const moduleEntry of modules) {
     const defaultTag = moduleEntry.info?.title ?? toTitle(moduleEntry.id);
     if (defaultTag) tags.set(defaultTag, moduleEntry.info?.description);
@@ -890,71 +903,75 @@ function buildOpenApiDocument(modules, options = {}) {
     for (const api of apis) {
       const routeDoc = collectRouteDoc(api, moduleEntry.id);
       const moduleTag = routeDoc?.tag ?? defaultTag;
-      const normalized = normalizePath(api.path ?? api.path ?? "");
-      const pathKey = normalized.path;
-      if (!doc.paths[pathKey]) doc.paths[pathKey] = {};
       const availableMethods = "handlers" in api ? HTTP_METHODS.filter((method) => typeof api.handlers?.[method] === "function") : [api.method];
-      for (const method of availableMethods) {
-        const methodLower = method.toLowerCase();
-        const existing = doc.paths[pathKey][methodLower];
-        if (existing) continue;
-        const metadata = "handlers" in api ? api.metadata?.[method] : void 0;
-        const methodDoc = routeDoc?.methods?.[method];
-        const summary = methodDoc?.summary ?? routeDoc?.summary ?? `${method} ${pathKey}`;
-        const baseDescription = methodDoc?.description ?? routeDoc?.description;
-        const meta = metadata && typeof metadata === "object" ? metadata : void 0;
-        const requireFeatures = Array.isArray(meta?.["requireFeatures"]) ? meta["requireFeatures"] : void 0;
-        const requireRoles = Array.isArray(meta?.["requireRoles"]) ? meta["requireRoles"] : void 0;
-        const requireAuth = meta?.["requireAuth"] === true;
-        const descriptionParts = [];
-        if (baseDescription) descriptionParts.push(baseDescription);
-        if (includeAccessControlMetadata && Array.isArray(requireFeatures) && requireFeatures.length) {
-          descriptionParts.push(`Requires features: ${requireFeatures.join(", ")}`);
-        }
-        if (includeAccessControlMetadata && Array.isArray(requireRoles) && requireRoles.length) {
-          descriptionParts.push(`Requires roles: ${requireRoles.join(", ")}`);
+      for (const normalized of expandOptionalPathParams(normalizePath(api.path ?? ""))) {
+        const pathKey = normalized.path;
+        if (!doc.paths[pathKey]) doc.paths[pathKey] = {};
+        for (const method of availableMethods) {
+          const methodLower = method.toLowerCase();
+          const operationKey = `${methodLower} ${pathKey}`;
+          const existing = doc.paths[pathKey][methodLower];
+          if (existing && (normalized.omittedParam || !derivedOperations.has(operationKey))) continue;
+          if (normalized.omittedParam) derivedOperations.add(operationKey);
+          else derivedOperations.delete(operationKey);
+          const metadata = "handlers" in api ? api.metadata?.[method] : void 0;
+          const methodDoc = routeDoc?.methods?.[method];
+          const summary = methodDoc?.summary ?? routeDoc?.summary ?? `${method} ${pathKey}`;
+          const baseDescription = methodDoc?.description ?? routeDoc?.description;
+          const meta = metadata && typeof metadata === "object" ? metadata : void 0;
+          const requireFeatures = Array.isArray(meta?.["requireFeatures"]) ? meta["requireFeatures"] : void 0;
+          const requireRoles = Array.isArray(meta?.["requireRoles"]) ? meta["requireRoles"] : void 0;
+          const requireAuth = meta?.["requireAuth"] === true;
+          const descriptionParts = [];
+          if (baseDescription) descriptionParts.push(baseDescription);
+          if (includeAccessControlMetadata && Array.isArray(requireFeatures) && requireFeatures.length) {
+            descriptionParts.push(`Requires features: ${requireFeatures.join(", ")}`);
+          }
+          if (includeAccessControlMetadata && Array.isArray(requireRoles) && requireRoles.length) {
+            descriptionParts.push(`Requires roles: ${requireRoles.join(", ")}`);
+          }
+          const querySchema = methodDoc?.query;
+          const pathSchema = methodDoc?.pathParams ?? routeDoc?.pathParams;
+          const headerSchema = methodDoc?.headers;
+          const requestBody = methodDoc?.requestBody;
+          const examples = collectExamples(querySchema, requestBody?.schema, pathSchema, headerSchema, metadata);
+          const curlSample = buildCurlSample(
+            method,
+            pathKey,
+            normalized.params,
+            examples,
+            options.baseUrlForExamples ?? "https://api.open-mercato.local",
+            metadata,
+            requestBody
+          );
+          doc.paths[pathKey][methodLower] = {
+            operationId: methodDoc?.operationId ? normalized.omittedParam ? `${methodDoc.operationId}_without_${normalizeOperationIdSegment(normalized.omittedParam)}` : methodDoc.operationId : resolveOperationId(moduleEntry.id, pathKey, method),
+            summary,
+            description: descriptionParts.length ? descriptionParts.join("\n\n") : void 0,
+            tags: methodDoc?.tags ?? (moduleTag ? [moduleTag] : void 0),
+            deprecated: methodDoc?.deprecated,
+            externalDocs: methodDoc?.externalDocs,
+            parameters: [
+              ...buildParameters(pathSchema, "path", normalized.params),
+              ...buildParameters(querySchema, "query"),
+              ...buildParameters(headerSchema, "header")
+            ].filter(Boolean),
+            requestBody: buildRequestBody(requestBody),
+            responses: buildResponses(method, methodDoc?.responses, methodDoc?.errors, metadata),
+            security: buildSecurity(metadata, methodDoc, options.defaultSecurity),
+            "x-codeSamples": methodDoc?.codeSamples ?? [
+              {
+                lang: "curl",
+                label: "cURL",
+                source: curlSample
+              }
+            ],
+            ...includeAccessControlMetadata && Array.isArray(requireFeatures) && requireFeatures.length ? { "x-require-features": requireFeatures } : {},
+            ...includeAccessControlMetadata && Array.isArray(requireRoles) && requireRoles.length ? { "x-require-roles": requireRoles } : {},
+            ...requireAuth ? { "x-require-auth": true } : {},
+            ...methodDoc?.extensions ?? {}
+          };
         }
-        const querySchema = methodDoc?.query;
-        const pathSchema = methodDoc?.pathParams ?? routeDoc?.pathParams;
-        const headerSchema = methodDoc?.headers;
-        const requestBody = methodDoc?.requestBody;
-        const examples = collectExamples(querySchema, requestBody?.schema, pathSchema, headerSchema, metadata);
-        const curlSample = buildCurlSample(
-          method,
-          pathKey,
-          normalized.params,
-          examples,
-          options.baseUrlForExamples ?? "https://api.open-mercato.local",
-          metadata,
-          requestBody
-        );
-        doc.paths[pathKey][methodLower] = {
-          operationId: methodDoc?.operationId ?? resolveOperationId(moduleEntry.id, pathKey, method),
-          summary,
-          description: descriptionParts.length ? descriptionParts.join("\n\n") : void 0,
-          tags: methodDoc?.tags ?? (moduleTag ? [moduleTag] : void 0),
-          deprecated: methodDoc?.deprecated,
-          externalDocs: methodDoc?.externalDocs,
-          parameters: [
-            ...buildParameters(pathSchema, "path", normalized.params),
-            ...buildParameters(querySchema, "query"),
-            ...buildParameters(headerSchema, "header")
-          ].filter(Boolean),
-          requestBody: buildRequestBody(requestBody),
-          responses: buildResponses(method, methodDoc?.responses, methodDoc?.errors, metadata),
-          security: buildSecurity(metadata, methodDoc, options.defaultSecurity),
-          "x-codeSamples": methodDoc?.codeSamples ?? [
-            {
-              lang: "curl",
-              label: "cURL",
-              source: curlSample
-            }
-          ],
-          ...includeAccessControlMetadata && Array.isArray(requireFeatures) && requireFeatures.length ? { "x-require-features": requireFeatures } : {},
-          ...includeAccessControlMetadata && Array.isArray(requireRoles) && requireRoles.length ? { "x-require-roles": requireRoles } : {},
-          ...requireAuth ? { "x-require-auth": true } : {},
-          ...methodDoc?.extensions ?? {}
-        };
       }
     }
   }