@let-aurn/swagger-client 0.2.0 → 0.3.1

package/README.md

@@ -28,6 +28,7 @@ npx swagger-client generate --config=swagger-client.json
 
 - `operationId` uses the OpenAPI `operationId` as-is. This is the default.
 - `tagAndOperationId` prefixes endpoint exports with the first OpenAPI tag, unless the `operationId` already starts with that tag.
+- `namespaceTagAndOperationId` adds a document namespace before the tag and operation ID. Requires `endpoint-namespace`.
 
 With `tagAndOperationId`, an operation tagged `SomeController` with `operationId: "someEndpoint"` is generated as:
 
@@ -35,9 +36,49 @@ With `tagAndOperationId`, an operation tagged `SomeController` with `operationId
 ApiEndpoints.SomeController_someEndpoint
 ```
 
+To include a namespace, configure where it comes from in each Swagger document:
+
+```json
+{
+  "endpoint-name-strategy": "namespaceTagAndOperationId",
+  "endpoint-namespace": {
+    "pointer": "/servers/0/url",
+    "pattern": "^/([^/]+)"
+  }
+}
+```
+
+For `servers: [{ "url": "/some-namespace/v1" }]`, tag `SomeController`, and
+operation ID `someMethod`, this generates:
+
+```ts
+ApiEndpoints.SomeNamespace_SomeController_someMethod
+```
+
+`pointer` is a JSON Pointer relative to the document root. It can select any
+string field, including custom extensions. Array indexes are path segments;
+escape `/` in property names as `~1` and `~` as `~0`.
+For example, `{ "pointer": "/info/x-namespace" }` uses that field's entire value.
+
+`pattern` is an optional JavaScript regular expression without delimiters or
+flags. When present, its first capture group supplies the namespace; without
+capture groups, the full match is used. Omit it to use the entire selected string.
+The namespace is converted to PascalCase. Only the first tag is used; operations
+without tags receive the namespace and operation ID. Existing tag or namespace
+prefixes followed by `_` are not repeated. Name collisions receive numeric suffixes.
+
+Extraction runs separately for each Swagger file. Missing or non-string fields,
+unmatched patterns, and empty namespaces fail generation with a file-specific
+error. This setting affects endpoint names only, not request URLs.
+
 ## Angular
 
+Use `provideSwaggerClient` to register the client as
+`EnvironmentProviders` without spreading a provider array:
+
 ```ts
+import { provideSwaggerClient } from './api/generated/swagger-client';
+
 bootstrapApplication(AppComponent, {
   providers: [
     provideHttpClient(),
@@ -48,7 +89,39 @@ bootstrapApplication(AppComponent, {
 });
 ```
 
-Custom HTTP implementations are supported:
+Starting with version `0.3.1`, `provideSwaggerClient(config)` returns
+`EnvironmentProviders` for application or route configuration. Remove any spread
+operator (`...`) when registering it. Version `0.3.0` retains the `Provider[]`
+implementation.
+
+### Custom HTTP adapters
+
+Implement `SwaggerHttpClient` and pass the adapter class to `provideSwaggerClient`.
+The adapter receives `{ method, url, headers, query, body }` and returns an
+`Observable<T>` of the response body. For a transport returning `Promise<{ data: unknown }>`:
+
+```ts
+import { Injectable } from '@angular/core';
+import { defer, map, Observable } from 'rxjs';
+import type {
+  SwaggerHttpClient,
+  SwaggerHttpRequest
+} from './api/generated/swagger-client';
+import { NativeTransport } from './native-transport';
+
+@Injectable()
+export class MySwaggerHttpClient implements SwaggerHttpClient {
+  constructor(private readonly transport: NativeTransport) {}
+
+  request<T>(request: SwaggerHttpRequest): Observable<T> {
+    return defer(() => this.transport.request(request)).pipe(
+      map(response => response.data as T)
+    );
+  }
+}
+```
+
+Register the adapter class through `provideSwaggerClient`:
 
 ```ts
 provideSwaggerClient({

package/dist/core/endpoint-namespace.d.ts

@@ -0,0 +1,3 @@
+import type { EndpointNamespaceConfig } from "./types.js";
+export declare function validateEndpointNamespace(config: EndpointNamespaceConfig | undefined, source: string): void;
+export declare function extractEndpointNamespace(document: unknown, config: EndpointNamespaceConfig, source: string): string;

package/dist/core/endpoint-namespace.js

@@ -0,0 +1,40 @@
+import { toPascalCase } from "./names.js";
+export function validateEndpointNamespace(config, source) {
+    if (!config || typeof config.pointer !== "string" || !/^(?:\/(?:[^~]|~[01])*)*$/.test(config.pointer)) {
+        throw new Error(`${source}: "endpoint-namespace.pointer" must be a JSON Pointer (for example "/servers/0/url").`);
+    }
+    if (config.pattern !== undefined) {
+        if (typeof config.pattern !== "string") {
+            throw new Error(`${source}: "endpoint-namespace.pattern" must be a regex string.`);
+        }
+        try {
+            new RegExp(config.pattern);
+        }
+        catch {
+            throw new Error(`${source}: "endpoint-namespace.pattern" is not a valid regex.`);
+        }
+    }
+}
+export function extractEndpointNamespace(document, config, source) {
+    let value = document;
+    const tokens = config.pointer === "" ? [] : config.pointer.slice(1).split("/");
+    for (const token of tokens) {
+        const key = token.replace(/~1/g, "/").replace(/~0/g, "~");
+        if (value === null || typeof value !== "object" || !Object.hasOwn(value, key)) {
+            value = undefined;
+            break;
+        }
+        value = value[key];
+    }
+    if (typeof value !== "string") {
+        throw new Error(`${source}: namespace at "${config.pointer}" must be a string.`);
+    }
+    if (config.pattern !== undefined) {
+        const match = new RegExp(config.pattern).exec(value);
+        value = match ? (match.length > 1 ? match[1] : match[0]) : undefined;
+    }
+    if (typeof value !== "string" || !/[A-Za-z0-9]/.test(value)) {
+        throw new Error(`${source}: namespace extracted from "${config.pointer}" is empty or does not match the configured pattern.`);
+    }
+    return toPascalCase(value);
+}

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"]);
+    const project = await readOpenApiProject(config["swaggers-directory"], config["endpoint-name-strategy"], config["endpoint-namespace"]);
     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,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
+import { validateEndpointNamespace } from "./endpoint-namespace.js";
 /**
  * Loads and validates a swagger-client configuration file.
  *
@@ -31,8 +32,12 @@ function validateConfig(config, configPath) {
     }
     if (config["endpoint-name-strategy"] !== undefined &&
         config["endpoint-name-strategy"] !== "operationId" &&
-        config["endpoint-name-strategy"] !== "tagAndOperationId") {
-        throw new Error(`${configPath}: "endpoint-name-strategy" must be "operationId" or "tagAndOperationId".`);
+        config["endpoint-name-strategy"] !== "tagAndOperationId" &&
+        config["endpoint-name-strategy"] !== "namespaceTagAndOperationId") {
+        throw new Error(`${configPath}: "endpoint-name-strategy" must be "operationId", "tagAndOperationId", or "namespaceTagAndOperationId".`);
+    }
+    if (config["endpoint-namespace"] !== undefined || config["endpoint-name-strategy"] === "namespaceTagAndOperationId") {
+        validateEndpointNamespace(config["endpoint-namespace"], configPath);
     }
     for (const key of ["api-models.ts", "api-endpoints.ts", "client.ts"]) {
         if (!config.output?.[key]) {

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

@@ -1,10 +1,11 @@
-import type { EndpointNameStrategy, ProjectModel } from "./types.js";
+import type { EndpointNameStrategy, EndpointNamespaceConfig, ProjectModel } from "./types.js";
 /**
  * Reads OpenAPI JSON files from a directory and converts them to the generator project model.
  *
  * @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.
  * @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): Promise<ProjectModel>;
+export declare function readOpenApiProject(swaggerDirectory: string, endpointNameStrategy?: EndpointNameStrategy, endpointNamespace?: EndpointNamespaceConfig): Promise<ProjectModel>;

package/dist/core/read-openapi.js

@@ -2,16 +2,21 @@ import { readdir, readFile } from "node:fs/promises";
 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";
 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.
  *
  * @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.
  * @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") {
+export async function readOpenApiProject(swaggerDirectory, endpointNameStrategy = "operationId", endpointNamespace) {
+    if (endpointNameStrategy === "namespaceTagAndOperationId") {
+        validateEndpointNamespace(endpointNamespace, swaggerDirectory);
+    }
     const files = await findJsonFiles(swaggerDirectory);
     const schemas = [];
     const endpoints = [];
@@ -21,7 +26,10 @@ export async function readOpenApiProject(swaggerDirectory, endpointNameStrategy
         const document = JSON.parse(await readFile(file, "utf8"));
         const sourceFile = relative(swaggerDirectory, file);
         const schemaNameMap = collectSchemas(document, schemas, usedSchemaNames);
-        endpoints.push(...collectEndpoints(document, sourceFile, schemaNameMap, usedEndpointNames, endpointNameStrategy));
+        const namespace = endpointNameStrategy === "namespaceTagAndOperationId"
+            ? extractEndpointNamespace(document, endpointNamespace, sourceFile)
+            : undefined;
+        endpoints.push(...collectEndpoints(document, sourceFile, schemaNameMap, usedEndpointNames, endpointNameStrategy, namespace));
     }
     return { schemas, endpoints };
 }
@@ -58,7 +66,7 @@ function collectSchemas(document, schemas, usedSchemaNames) {
     }
     return schemaNameMap;
 }
-function collectEndpoints(document, sourceFile, schemaNameMap, usedEndpointNames, endpointNameStrategy) {
+function collectEndpoints(document, sourceFile, schemaNameMap, usedEndpointNames, endpointNameStrategy, namespace) {
     const endpoints = [];
     for (const [path, pathItem] of Object.entries(document.paths ?? {})) {
         if (!isRecord(pathItem)) {
@@ -69,7 +77,7 @@ function collectEndpoints(document, sourceFile, schemaNameMap, usedEndpointNames
                 continue;
             }
             const operationId = operation.operationId ?? fallbackOperationId(method, path);
-            const endpointName = uniqueName(endpointNameForOperation(operation, operationId, endpointNameStrategy), usedEndpointNames);
+            const endpointName = uniqueName(endpointNameForOperation(operation, operationId, endpointNameStrategy, namespace), usedEndpointNames);
             const parameters = operation.parameters ?? [];
             endpoints.push({
                 name: endpointName,
@@ -87,20 +95,20 @@ function collectEndpoints(document, sourceFile, schemaNameMap, usedEndpointNames
     }
     return endpoints;
 }
-function endpointNameForOperation(operation, operationId, strategy) {
+function endpointNameForOperation(operation, operationId, strategy, namespace) {
     const operationName = ensureIdentifier(operationId, "endpoint");
-    if (strategy !== "tagAndOperationId") {
+    if (strategy === "operationId") {
         return operationName;
     }
     const tag = operation.tags?.[0];
-    if (!tag) {
-        return operationName;
-    }
-    const tagName = ensureIdentifier(toPascalCase(tag), "endpoint");
-    if (operationName === tagName || operationName.startsWith(`${tagName}_`)) {
-        return operationName;
+    const tagName = tag ? ensureIdentifier(toPascalCase(tag), "endpoint") : undefined;
+    const taggedName = !tagName || operationName === tagName || operationName.startsWith(`${tagName}_`)
+        ? operationName
+        : `${tagName}_${operationName}`;
+    if (!namespace || taggedName === namespace || taggedName.startsWith(`${namespace}_`)) {
+        return taggedName;
     }
-    return `${tagName}_${operationName}`;
+    return `${namespace}_${taggedName}`;
 }
 function variablesFor(parameters, location, schemaNameMap) {
     return parameters

package/dist/core/types.d.ts

@@ -1,9 +1,16 @@
 export type ClientKind = "angular" | "react";
-export type EndpointNameStrategy = "operationId" | "tagAndOperationId";
+export type EndpointNameStrategy = "operationId" | "tagAndOperationId" | "namespaceTagAndOperationId";
+export interface EndpointNamespaceConfig {
+    /** JSON Pointer to a string in each OpenAPI document. */
+    pointer: string;
+    /** Optional regex: uses the first capture group, or the full match if none exists. */
+    pattern?: string;
+}
 export interface SwaggerClientConfig {
     client: ClientKind;
     "swaggers-directory": string;
     "endpoint-name-strategy"?: EndpointNameStrategy;
+    "endpoint-namespace"?: EndpointNamespaceConfig;
     output: {
         "api-models.ts": string;
         "api-endpoints.ts": string;

package/dist/generators/angular-client.js

@@ -4,7 +4,7 @@ export function emitAngularClient(options = {}) {
 /* eslint-disable */
 // This file was generated by @let-aurn/swagger-client.
 import { HttpClient, HttpHeaders, HttpParams } from '@angular/common/http';
-import { Inject, Injectable, InjectionToken, Provider, Type } from '@angular/core';
+import { EnvironmentProviders, Inject, Injectable, InjectionToken, makeEnvironmentProviders, Type } from '@angular/core';
 import { Observable } from 'rxjs';
 import type {
   AnyApiEndpoint,
@@ -130,17 +130,17 @@ export class SwaggerClientService {
 }
 
 /**
- * Provides the generated Angular swagger client and its HTTP adapter.
+ * Provides the generated Angular swagger client and its HTTP adapter in an environment injector.
  *
  * @param config The swagger client runtime configuration.
- * @returns Angular providers for the generated client.
+ * @returns Environment providers for application or route configuration.
  */
-export function provideSwaggerClient(config: SwaggerClientConfig): Provider[] {
-  return [
+export function provideSwaggerClient(config: SwaggerClientConfig): EnvironmentProviders {
+  return makeEnvironmentProviders([
     { provide: SWAGGER_CLIENT_CONFIG, useValue: config },
     { provide: SWAGGER_HTTP_CLIENT, useClass: config.httpClient ?? AngularSwaggerHttpClient },
     SwaggerClientService
-  ];
+  ]);
 }
 
 function buildRequest<TEndpoint extends AnyApiEndpoint>(

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { ClientKind, EndpointModel, ProjectModel, SchemaModel, SwaggerClientConfig, VariableModel } from "./core/types.js";
+export type { ClientKind, EndpointNameStrategy, EndpointNamespaceConfig, EndpointModel, ProjectModel, SchemaModel, SwaggerClientConfig, VariableModel } from "./core/types.js";
 export { generate } from "./core/generate.js";
 export { loadConfig } from "./core/load-config.js";
 export { readOpenApiProject } from "./core/read-openapi.js";

package/package.json

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