@let-aurn/swagger-client 0.3.2 → 0.3.3

package/README.md

@@ -24,6 +24,23 @@ npx swagger-client generate --config=swagger-client.json
 
 `client` can be `angular` or `react`.
 
+`serverUrlIndex` is optional and selects a zero-based index from each document's
+top-level `servers` array to prefix generated endpoint paths:
+
+```json
+{
+  "serverUrlIndex": 0
+}
+```
+
+For `servers: [{ "url": "/some-api/V01/xxx" }]`, the endpoint `/posts/{id}`
+gets the path `/some-api/V01/xxx/posts/{id}` in `api-endpoints.ts`. Relative
+server prefixes are appended to the client's configured `baseUrl` when making
+requests. Slashes at the join are normalized; an empty operation path uses the
+selected server URL exactly, without adding a trailing slash. Omitting this option keeps the
+original endpoint paths. Invalid indexes or missing, empty, or non-string
+selected URLs fail generation; URL errors identify the source file.
+
 `endpoint-name-strategy` is optional:
 
 - `operationId` uses the OpenAPI `operationId` as-is. This is the default.

package/dist/core/generate.js

@@ -13,7 +13,7 @@ import { emitReactClient } from "../generators/react-client.js";
  * @throws Error when OpenAPI files cannot be read or generated files cannot be written.
  */
 export async function generate(config) {
-    const project = await readOpenApiProject(config["swaggers-directory"], config["endpoint-name-strategy"], config["endpoint-namespace"]);
+    const project = await readOpenApiProject(config["swaggers-directory"], config["endpoint-name-strategy"], config["endpoint-namespace"], config.serverUrlIndex);
     const modelsPath = config.output["api-models.ts"];
     const endpointsPath = config.output["api-endpoints.ts"];
     const clientPath = config.output["client.ts"];

package/dist/core/load-config.js

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { validateEndpointNamespace } from "./endpoint-namespace.js";
+import { validateServerUrlIndex } from "./server-url.js";
 /**
  * Loads and validates a swagger-client configuration file.
  *
@@ -24,6 +25,7 @@ export async function loadConfig(configPath) {
     };
 }
 function validateConfig(config, configPath) {
+    validateServerUrlIndex(config.serverUrlIndex, configPath);
     if (config.client !== "angular" && config.client !== "react") {
         throw new Error(`${configPath}: "client" must be "angular" or "react".`);
     }

package/dist/core/read-openapi.d.ts

@@ -5,7 +5,8 @@ import type { EndpointNameStrategy, EndpointNamespaceConfig, ProjectModel } from
  * @param swaggerDirectory The directory containing one or more OpenAPI JSON files.
  * @param endpointNameStrategy The strategy used to name generated endpoint constants.
  * @param endpointNamespace Configurable document field and optional namespace extraction regex.
+ * @param serverUrlIndex Optional document server URL index to prefix endpoint paths with.
  * @returns The normalized schemas and endpoints discovered in the OpenAPI files.
  * @throws Error when a JSON file cannot be read or parsed.
  */
-export declare function readOpenApiProject(swaggerDirectory: string, endpointNameStrategy?: EndpointNameStrategy, endpointNamespace?: EndpointNamespaceConfig): Promise<ProjectModel>;
+export declare function readOpenApiProject(swaggerDirectory: string, endpointNameStrategy?: EndpointNameStrategy, endpointNamespace?: EndpointNamespaceConfig, serverUrlIndex?: number): Promise<ProjectModel>;

package/dist/core/read-openapi.js

@@ -3,6 +3,7 @@ import { join, relative } from "node:path";
 import { schemaToType } from "./schema-to-typescript.js";
 import { ensureIdentifier, toPascalCase, uniqueName } from "./names.js";
 import { extractEndpointNamespace, validateEndpointNamespace } from "./endpoint-namespace.js";
+import { selectServerUrl, validateServerUrlIndex } from "./server-url.js";
 const HTTP_METHODS = new Set(["get", "post", "put", "patch", "delete", "head", "options"]);
 /**
  * Reads OpenAPI JSON files from a directory and converts them to the generator project model.
@@ -10,10 +11,12 @@ const HTTP_METHODS = new Set(["get", "post", "put", "patch", "delete", "head", "
  * @param swaggerDirectory The directory containing one or more OpenAPI JSON files.
  * @param endpointNameStrategy The strategy used to name generated endpoint constants.
  * @param endpointNamespace Configurable document field and optional namespace extraction regex.
+ * @param serverUrlIndex Optional document server URL index to prefix endpoint paths with.
  * @returns The normalized schemas and endpoints discovered in the OpenAPI files.
  * @throws Error when a JSON file cannot be read or parsed.
  */
-export async function readOpenApiProject(swaggerDirectory, endpointNameStrategy = "operationId", endpointNamespace) {
+export async function readOpenApiProject(swaggerDirectory, endpointNameStrategy = "operationId", endpointNamespace, serverUrlIndex) {
+    validateServerUrlIndex(serverUrlIndex, swaggerDirectory);
     if (endpointNameStrategy === "namespaceTagAndOperationId") {
         validateEndpointNamespace(endpointNamespace, swaggerDirectory);
     }
@@ -25,11 +28,12 @@ export async function readOpenApiProject(swaggerDirectory, endpointNameStrategy
     for (const file of files) {
         const document = JSON.parse(await readFile(file, "utf8"));
         const sourceFile = relative(swaggerDirectory, file);
+        const serverUrl = selectServerUrl(document, serverUrlIndex, sourceFile);
         const schemaNameMap = collectSchemas(document, schemas, usedSchemaNames);
         const namespace = endpointNameStrategy === "namespaceTagAndOperationId"
             ? extractEndpointNamespace(document, endpointNamespace, sourceFile)
             : undefined;
-        endpoints.push(...collectEndpoints(document, sourceFile, schemaNameMap, usedEndpointNames, endpointNameStrategy, namespace));
+        endpoints.push(...collectEndpoints(document, sourceFile, schemaNameMap, usedEndpointNames, endpointNameStrategy, namespace, serverUrl));
     }
     return { schemas, endpoints };
 }
@@ -66,7 +70,7 @@ function collectSchemas(document, schemas, usedSchemaNames) {
     }
     return schemaNameMap;
 }
-function collectEndpoints(document, sourceFile, schemaNameMap, usedEndpointNames, endpointNameStrategy, namespace) {
+function collectEndpoints(document, sourceFile, schemaNameMap, usedEndpointNames, endpointNameStrategy, namespace, serverUrl = "") {
     const endpoints = [];
     for (const [path, pathItem] of Object.entries(document.paths ?? {})) {
         if (!isRecord(pathItem)) {
@@ -82,7 +86,7 @@ function collectEndpoints(document, sourceFile, schemaNameMap, usedEndpointNames
             endpoints.push({
                 name: endpointName,
                 method: method.toUpperCase(),
-                path,
+                path: serverUrl && path ? `${serverUrl.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}` : serverUrl || path,
                 operationId,
                 sourceFile,
                 pathVariables: variablesFor(parameters, "path", schemaNameMap),

package/dist/core/server-url.d.ts

@@ -0,0 +1,3 @@
+import type { OpenApiDocument } from "./types.js";
+export declare function validateServerUrlIndex(index: number | undefined, source: string): void;
+export declare function selectServerUrl(document: OpenApiDocument, index: number | undefined, sourceFile: string): string;

package/dist/core/server-url.js

@@ -0,0 +1,15 @@
+export function validateServerUrlIndex(index, source) {
+    if (index !== undefined && (!Number.isSafeInteger(index) || index < 0)) {
+        throw new Error(`${source}: "serverUrlIndex" must be a non-negative safe integer.`);
+    }
+}
+export function selectServerUrl(document, index, sourceFile) {
+    if (index === undefined) {
+        return "";
+    }
+    const url = Array.isArray(document.servers) ? document.servers[index]?.url : undefined;
+    if (typeof url !== "string" || url.trim() === "") {
+        throw new Error(`${sourceFile}: servers[${index}].url must be a non-empty string when "serverUrlIndex" is provided.`);
+    }
+    return url;
+}

package/dist/core/types.d.ts

@@ -11,6 +11,8 @@ export interface SwaggerClientConfig {
     "swaggers-directory": string;
     "endpoint-name-strategy"?: EndpointNameStrategy;
     "endpoint-namespace"?: EndpointNamespaceConfig;
+    /** Index of the document server URL to prefix endpoint paths with. */
+    serverUrlIndex?: number;
     output: {
         "api-models.ts": string;
         "api-endpoints.ts": string;
@@ -46,6 +48,9 @@ export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" |
 export interface OpenApiDocument {
     openapi?: string;
     swagger?: string;
+    servers?: {
+        url: string;
+    }[];
     info?: {
         title?: string;
         version?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@let-aurn/swagger-client",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Generate typed Angular and React clients from OpenAPI JSON files.",
   "type": "module",
   "bin": {