@let-aurn/swagger-client 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# Swagger Client
+
+Generate typed Angular and React clients from OpenAPI JSON files.
+
+```sh
+npx swagger-client generate
+npx swagger-client generate --config=swagger-client.json
+```
+
+## Config
+
+```json
+{
+  "client": "angular",
+  "swaggers-directory": "path/to/swaggers",
+  "endpoint-name-strategy": "operationId",
+  "output": {
+    "api-models.ts": "src/app/api/generated/api-models.ts",
+    "api-endpoints.ts": "src/app/api/generated/api-endpoints.ts",
+    "client.ts": "src/app/api/generated/swagger-client.ts"
+  }
+}
+```
+
+`client` can be `angular` or `react`.
+
+`endpoint-name-strategy` is optional:
+
+- `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.
+
+With `tagAndOperationId`, an operation tagged `SomeController` with `operationId: "someEndpoint"` is generated as:
+
+```ts
+ApiEndpoints.SomeController_someEndpoint
+```
+
+## Angular
+
+```ts
+bootstrapApplication(AppComponent, {
+  providers: [
+    provideHttpClient(),
+    provideSwaggerClient({
+      baseUrl: 'https://api.example.com'
+    })
+  ]
+});
+```
+
+Custom HTTP implementations are supported:
+
+```ts
+provideSwaggerClient({
+  baseUrl: 'https://api.example.com',
+  httpClient: MySwaggerHttpClient
+});
+```
+
+## React
+
+```ts
+const client = useSwaggerClient(ApiEndpoints.PostsController_getPost, {
+  baseUrl: 'https://api.example.com'
+});
+
+const post = await client.request({
+  pathVariables: { id: 123 }
+});
+```

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { generate } from "../core/generate.js";
+import { loadConfig } from "../core/load-config.js";
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    if (command !== "generate") {
+        printHelp();
+        process.exit(command ? 1 : 0);
+    }
+    const configPath = readConfigPath(args) ?? "swagger-client.json";
+    const config = await loadConfig(resolve(configPath));
+    await generate(config);
+    console.log("Swagger client generated.");
+}
+function readConfigPath(args) {
+    const inline = args.find((arg) => arg.startsWith("--config="));
+    if (inline) {
+        return inline.slice("--config=".length);
+    }
+    const index = args.indexOf("--config");
+    return index === -1 ? undefined : args[index + 1];
+}
+function printHelp() {
+    console.log(`Usage:
+  swagger-client generate
+  swagger-client generate --config=swagger-client.json`);
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+});

package/dist/core/generate.d.ts

@@ -0,0 +1,9 @@
+import type { SwaggerClientConfig } from "./types.js";
+/**
+ * Generates TypeScript model, endpoint, and client files from a swagger-client configuration.
+ *
+ * @param config The resolved swagger-client generation configuration.
+ * @returns A promise that resolves when all generated files have been written.
+ * @throws Error when OpenAPI files cannot be read or generated files cannot be written.
+ */
+export declare function generate(config: SwaggerClientConfig): Promise<void>;

package/dist/core/generate.js

@@ -0,0 +1,36 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, relative } from "node:path";
+import { readOpenApiProject } from "./read-openapi.js";
+import { emitModels } from "../generators/models.js";
+import { emitEndpoints } from "../generators/endpoints.js";
+import { emitAngularClient } from "../generators/angular-client.js";
+import { emitReactClient } from "../generators/react-client.js";
+/**
+ * Generates TypeScript model, endpoint, and client files from a swagger-client configuration.
+ *
+ * @param config The resolved swagger-client generation configuration.
+ * @returns A promise that resolves when all generated files have been written.
+ * @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 modelsPath = config.output["api-models.ts"];
+    const endpointsPath = config.output["api-endpoints.ts"];
+    const clientPath = config.output["client.ts"];
+    await writeGeneratedFile(modelsPath, emitModels(project));
+    await writeGeneratedFile(endpointsPath, emitEndpoints(project, {
+        modelsImportPath: toTypeScriptImportPath(endpointsPath, modelsPath)
+    }));
+    await writeGeneratedFile(clientPath, config.client === "angular"
+        ? emitAngularClient({ endpointsImportPath: toTypeScriptImportPath(clientPath, endpointsPath) })
+        : emitReactClient({ endpointsImportPath: toTypeScriptImportPath(clientPath, endpointsPath) }));
+}
+async function writeGeneratedFile(path, content) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${content.trimEnd()}\n`, "utf8");
+}
+function toTypeScriptImportPath(fromFile, toFile) {
+    const withoutExtension = relative(dirname(fromFile), toFile).replace(/\.ts$/, "");
+    const normalized = withoutExtension.split("\\").join("/");
+    return normalized.startsWith(".") ? normalized : `./${normalized}`;
+}

package/dist/core/load-config.d.ts

@@ -0,0 +1,9 @@
+import type { SwaggerClientConfig } from "./types.js";
+/**
+ * Loads and validates a swagger-client configuration file.
+ *
+ * @param configPath The path to the JSON configuration file.
+ * @returns The resolved swagger-client configuration.
+ * @throws Error when the configuration file is missing, invalid JSON, or structurally invalid.
+ */
+export declare function loadConfig(configPath: string): Promise<SwaggerClientConfig>;

package/dist/core/load-config.js

@@ -0,0 +1,42 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+/**
+ * Loads and validates a swagger-client configuration file.
+ *
+ * @param configPath The path to the JSON configuration file.
+ * @returns The resolved swagger-client configuration.
+ * @throws Error when the configuration file is missing, invalid JSON, or structurally invalid.
+ */
+export async function loadConfig(configPath) {
+    const absolutePath = resolve(configPath);
+    const raw = await readFile(absolutePath, "utf8");
+    const config = JSON.parse(raw);
+    validateConfig(config, absolutePath);
+    return {
+        ...config,
+        "swaggers-directory": resolve(config["swaggers-directory"]),
+        output: {
+            "api-models.ts": resolve(config.output["api-models.ts"]),
+            "api-endpoints.ts": resolve(config.output["api-endpoints.ts"]),
+            "client.ts": resolve(config.output["client.ts"])
+        }
+    };
+}
+function validateConfig(config, configPath) {
+    if (config.client !== "angular" && config.client !== "react") {
+        throw new Error(`${configPath}: "client" must be "angular" or "react".`);
+    }
+    if (!config["swaggers-directory"]) {
+        throw new Error(`${configPath}: "swaggers-directory" is required.`);
+    }
+    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".`);
+    }
+    for (const key of ["api-models.ts", "api-endpoints.ts", "client.ts"]) {
+        if (!config.output?.[key]) {
+            throw new Error(`${configPath}: output["${key}"] is required.`);
+        }
+    }
+}

package/dist/core/names.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Converts a value to a valid PascalCase TypeScript identifier.
+ *
+ * @param value The value to convert.
+ * @returns A PascalCase identifier.
+ */
+export declare function toPascalCase(value: string): string;
+/**
+ * Ensures a value is a valid TypeScript identifier.
+ *
+ * @param value The value to sanitize.
+ * @param fallback The prefix to use when the value cannot start an identifier.
+ * @returns A valid TypeScript identifier.
+ */
+export declare function ensureIdentifier(value: string, fallback: string): string;
+/**
+ * Returns a name that is unique within a mutable set of used names.
+ *
+ * @param baseName The preferred name.
+ * @param usedNames The set of names already reserved.
+ * @returns The unique name that was added to the set.
+ */
+export declare function uniqueName(baseName: string, usedNames: Set<string>): string;
+/**
+ * Serializes a string as a TypeScript string literal.
+ *
+ * @param value The string value to quote.
+ * @returns A quoted string literal.
+ */
+export declare function quote(value: string): string;

package/dist/core/names.js

@@ -0,0 +1,87 @@
+const RESERVED_WORDS = new Set([
+    "break",
+    "case",
+    "catch",
+    "class",
+    "const",
+    "continue",
+    "debugger",
+    "default",
+    "delete",
+    "do",
+    "else",
+    "export",
+    "extends",
+    "finally",
+    "for",
+    "function",
+    "if",
+    "import",
+    "in",
+    "instanceof",
+    "new",
+    "return",
+    "super",
+    "switch",
+    "this",
+    "throw",
+    "try",
+    "typeof",
+    "var",
+    "void",
+    "while",
+    "with",
+    "yield"
+]);
+/**
+ * Converts a value to a valid PascalCase TypeScript identifier.
+ *
+ * @param value The value to convert.
+ * @returns A PascalCase identifier.
+ */
+export function toPascalCase(value) {
+    const words = value
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean);
+    const name = words.map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join("");
+    return ensureIdentifier(name || "GeneratedType", "GeneratedType");
+}
+/**
+ * Ensures a value is a valid TypeScript identifier.
+ *
+ * @param value The value to sanitize.
+ * @param fallback The prefix to use when the value cannot start an identifier.
+ * @returns A valid TypeScript identifier.
+ */
+export function ensureIdentifier(value, fallback) {
+    const cleaned = value.replace(/[^A-Za-z0-9_$]/g, "");
+    const withStart = /^[A-Za-z_$]/.test(cleaned) ? cleaned : `${fallback}${cleaned}`;
+    return RESERVED_WORDS.has(withStart) ? `${withStart}Value` : withStart;
+}
+/**
+ * Returns a name that is unique within a mutable set of used names.
+ *
+ * @param baseName The preferred name.
+ * @param usedNames The set of names already reserved.
+ * @returns The unique name that was added to the set.
+ */
+export function uniqueName(baseName, usedNames) {
+    let name = baseName;
+    let index = 2;
+    while (usedNames.has(name)) {
+        name = `${baseName}${index}`;
+        index += 1;
+    }
+    usedNames.add(name);
+    return name;
+}
+/**
+ * Serializes a string as a TypeScript string literal.
+ *
+ * @param value The string value to quote.
+ * @returns A quoted string literal.
+ */
+export function quote(value) {
+    return JSON.stringify(value);
+}

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

@@ -0,0 +1,10 @@
+import type { EndpointNameStrategy, 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.
+ * @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>;

package/dist/core/read-openapi.js

@@ -0,0 +1,169 @@
+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";
+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.
+ * @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") {
+    const files = await findJsonFiles(swaggerDirectory);
+    const schemas = [];
+    const endpoints = [];
+    const usedSchemaNames = new Set();
+    const usedEndpointNames = new Set();
+    for (const file of files) {
+        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));
+    }
+    return { schemas, endpoints };
+}
+async function findJsonFiles(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...await findJsonFiles(path));
+        }
+        else if (entry.isFile() && entry.name.endsWith(".json")) {
+            files.push(path);
+        }
+    }
+    return files.sort();
+}
+function collectSchemas(document, schemas, usedSchemaNames) {
+    const schemaNameMap = new Map();
+    const sourceSchemas = document.components?.schemas ?? document.definitions ?? {};
+    for (const rawName of Object.keys(sourceSchemas)) {
+        const generatedName = uniqueName(toPascalCase(rawName), usedSchemaNames);
+        schemaNameMap.set(rawName, generatedName);
+    }
+    for (const [rawName, schema] of Object.entries(sourceSchemas)) {
+        const generatedName = schemaNameMap.get(rawName);
+        if (!generatedName) {
+            continue;
+        }
+        schemas.push({
+            name: generatedName,
+            schema: rewriteRefs(schema, schemaNameMap)
+        });
+    }
+    return schemaNameMap;
+}
+function collectEndpoints(document, sourceFile, schemaNameMap, usedEndpointNames, endpointNameStrategy) {
+    const endpoints = [];
+    for (const [path, pathItem] of Object.entries(document.paths ?? {})) {
+        if (!isRecord(pathItem)) {
+            continue;
+        }
+        for (const [method, operation] of Object.entries(pathItem)) {
+            if (!HTTP_METHODS.has(method) || !isOperation(operation)) {
+                continue;
+            }
+            const operationId = operation.operationId ?? fallbackOperationId(method, path);
+            const endpointName = uniqueName(endpointNameForOperation(operation, operationId, endpointNameStrategy), usedEndpointNames);
+            const parameters = operation.parameters ?? [];
+            endpoints.push({
+                name: endpointName,
+                method: method.toUpperCase(),
+                path,
+                operationId,
+                sourceFile,
+                pathVariables: variablesFor(parameters, "path", schemaNameMap),
+                queryVariables: variablesFor(parameters, "query", schemaNameMap),
+                headerVariables: variablesFor(parameters, "header", schemaNameMap),
+                bodyType: requestBodyType(operation, schemaNameMap),
+                responseType: responseType(operation.responses, schemaNameMap)
+            });
+        }
+    }
+    return endpoints;
+}
+function endpointNameForOperation(operation, operationId, strategy) {
+    const operationName = ensureIdentifier(operationId, "endpoint");
+    if (strategy !== "tagAndOperationId") {
+        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;
+    }
+    return `${tagName}_${operationName}`;
+}
+function variablesFor(parameters, location, schemaNameMap) {
+    return parameters
+        .filter((parameter) => parameter.in === location)
+        .map((parameter) => ({
+        name: parameter.name,
+        type: schemaToType(rewriteRefs(parameter.schema ?? { type: "string" }, schemaNameMap)),
+        required: parameter.required === true || location === "path"
+    }));
+}
+function requestBodyType(operation, schemaNameMap) {
+    const schema = preferredContentSchema(operation.requestBody?.content);
+    return schema ? schemaToType(rewriteRefs(schema, schemaNameMap)) : null;
+}
+function responseType(responses, schemaNameMap) {
+    const response = responses?.["200"] ?? responses?.["201"] ?? responses?.["204"] ?? firstSuccessResponse(responses);
+    const schema = preferredContentSchema(response?.content);
+    if (!schema || response === responses?.["204"]) {
+        return "void";
+    }
+    return schemaToType(rewriteRefs(schema, schemaNameMap));
+}
+function firstSuccessResponse(responses) {
+    return Object.entries(responses ?? {}).find(([status]) => status.startsWith("2"))?.[1];
+}
+function preferredContentSchema(content) {
+    return content?.["application/json"]?.schema ?? Object.values(content ?? {})[0]?.schema;
+}
+function rewriteRefs(schema, schemaNameMap) {
+    if (!schema) {
+        return schema;
+    }
+    const clone = structuredClone(schema);
+    rewriteRefsInPlace(clone, schemaNameMap);
+    return clone;
+}
+function rewriteRefsInPlace(schema, schemaNameMap) {
+    if (schema.$ref) {
+        const rawName = schema.$ref.split("/").at(-1);
+        const mappedName = rawName ? schemaNameMap.get(rawName) : undefined;
+        if (mappedName) {
+            schema.$ref = `#/components/schemas/${mappedName}`;
+        }
+    }
+    for (const child of [
+        ...Object.values(schema.properties ?? {}),
+        schema.items,
+        ...(schema.allOf ?? []),
+        ...(schema.oneOf ?? []),
+        ...(schema.anyOf ?? []),
+        typeof schema.additionalProperties === "object" ? schema.additionalProperties : undefined
+    ]) {
+        if (child) {
+            rewriteRefsInPlace(child, schemaNameMap);
+        }
+    }
+}
+function fallbackOperationId(method, path) {
+    return `${method}_${path.replace(/[{}]/g, "").replace(/[^A-Za-z0-9]+/g, "_")}`;
+}
+function isOperation(value) {
+    return isRecord(value);
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/dist/core/schema-to-typescript.d.ts

@@ -0,0 +1,17 @@
+import type { OpenApiSchema } from "./types.js";
+/**
+ * Converts an OpenAPI schema to a TypeScript type expression.
+ *
+ * @param schema The OpenAPI schema to convert.
+ * @param fallback The type to use when the schema cannot be inferred.
+ * @returns A TypeScript type expression.
+ */
+export declare function schemaToType(schema: OpenApiSchema | undefined, fallback?: string): string;
+/**
+ * Emits a TypeScript declaration for a named OpenAPI schema.
+ *
+ * @param name The TypeScript declaration name.
+ * @param schema The OpenAPI schema to emit.
+ * @returns A TypeScript interface or type alias declaration.
+ */
+export declare function emitSchemaInterface(name: string, schema: OpenApiSchema): string;

package/dist/core/schema-to-typescript.js

@@ -0,0 +1,92 @@
+import { quote, toPascalCase } from "./names.js";
+/**
+ * Converts an OpenAPI schema to a TypeScript type expression.
+ *
+ * @param schema The OpenAPI schema to convert.
+ * @param fallback The type to use when the schema cannot be inferred.
+ * @returns A TypeScript type expression.
+ */
+export function schemaToType(schema, fallback = "unknown") {
+    if (!schema) {
+        return fallback;
+    }
+    let type = schemaToNonNullableType(schema, fallback);
+    if (schema.nullable) {
+        type = `${type} | null`;
+    }
+    return type;
+}
+/**
+ * Emits a TypeScript declaration for a named OpenAPI schema.
+ *
+ * @param name The TypeScript declaration name.
+ * @param schema The OpenAPI schema to emit.
+ * @returns A TypeScript interface or type alias declaration.
+ */
+export function emitSchemaInterface(name, schema) {
+    if (schema.type === "object" || schema.properties || schema.additionalProperties) {
+        return emitObjectInterface(name, schema);
+    }
+    return `export type ${name} = ${schemaToType(schema)};`;
+}
+function emitObjectInterface(name, schema) {
+    const required = new Set(schema.required ?? []);
+    const lines = [`export interface ${name} {`];
+    for (const [propertyName, propertySchema] of Object.entries(schema.properties ?? {})) {
+        const optional = required.has(propertyName) ? "" : "?";
+        lines.push(`  ${propertyKey(propertyName)}${optional}: ${schemaToType(propertySchema)};`);
+    }
+    if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
+        lines.push(`  [key: string]: ${schemaToType(schema.additionalProperties)};`);
+    }
+    else if (schema.additionalProperties === true) {
+        lines.push("  [key: string]: unknown;");
+    }
+    lines.push("}");
+    return lines.join("\n");
+}
+function schemaToNonNullableType(schema, fallback) {
+    if (schema.$ref) {
+        return toPascalCase(schema.$ref.split("/").at(-1) ?? fallback);
+    }
+    if (schema.enum) {
+        return schema.enum.map((value) => JSON.stringify(value)).join(" | ") || fallback;
+    }
+    if (schema.allOf) {
+        return schema.allOf.map((item) => schemaToType(item, fallback)).join(" & ") || fallback;
+    }
+    if (schema.oneOf || schema.anyOf) {
+        return (schema.oneOf ?? schema.anyOf ?? []).map((item) => schemaToType(item, fallback)).join(" | ") || fallback;
+    }
+    if (schema.type === "array") {
+        return `${schemaToType(schema.items, "unknown")}[]`;
+    }
+    if (schema.type === "object" || schema.properties) {
+        const entries = Object.entries(schema.properties ?? {});
+        if (entries.length === 0) {
+            if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
+                return `Record<string, ${schemaToType(schema.additionalProperties)}>`;
+            }
+            return "Record<string, unknown>";
+        }
+        const required = new Set(schema.required ?? []);
+        const props = entries.map(([name, propSchema]) => {
+            const optional = required.has(name) ? "" : "?";
+            return `${propertyKey(name)}${optional}: ${schemaToType(propSchema)}`;
+        });
+        return `{ ${props.join("; ")} }`;
+    }
+    if (schema.type === "integer" || schema.type === "number") {
+        return "number";
+    }
+    if (schema.type === "boolean") {
+        return "boolean";
+    }
+    if (schema.type === "string") {
+        return "string";
+    }
+    return fallback;
+}
+function propertyKey(name) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : quote(name);
+}