Continue implementing OpenAPI 3.2.0

Author: SamuelMarks

src/service/emit/utility/server-url.generator.ts

@@ -0,0 +1,99 @@
+// src/service/emit/utility/server-url.generator.ts
+
+import * as path from "node:path";
+import { Project, VariableDeclarationKind } from "ts-morph";
+import { UTILITY_GENERATOR_HEADER_COMMENT } from "../../../core/constants.js";
+import { SwaggerParser } from "../../../core/parser.js";
+
+/**
+ * Generates the `utils/server-url.ts` file.
+ * This file provides constants and a helper function to access and construct
+ * server URLs as defined in the OpenAPI spec, including variable substitution logic.
+ */
+export class ServerUrlGenerator {
+    constructor(private parser: SwaggerParser, private project: Project) {
+    }
+
+    public generate(outputDir: string): void {
+        if (this.parser.servers.length === 0) {
+            // No servers defined in spec, skip generation.
+            return;
+        }
+
+        const utilsDir = path.join(outputDir, "utils");
+        const filePath = path.join(utilsDir, "server-url.ts");
+
+        const sourceFile = this.project.createSourceFile(filePath, "", { overwrite: true });
+
+        sourceFile.insertText(0, UTILITY_GENERATOR_HEADER_COMMENT);
+
+        // Define the type for Server Object to keep the generated code clean and typed
+        sourceFile.addInterface({
+            name: "ServerConfiguration",
+            isExported: true,
+            properties: [
+                { name: "url", type: "string" },
+                { name: "description", type: "string", hasQuestionToken: true },
+                {
+                    name: "variables",
+                    hasQuestionToken: true,
+                    type: "Record<string, { enum?: string[]; default: string; description?: string; }>"
+                }
+            ]
+        });
+
+        // Export the servers array
+        sourceFile.addVariableStatement({
+            isExported: true,
+            declarationKind: VariableDeclarationKind.Const,
+            declarations: [{
+                name: "API_SERVERS",
+                type: "ServerConfiguration[]",
+                initializer: JSON.stringify(this.parser.servers, null, 2)
+            }],
+            docs: ["The list of servers defined in the OpenAPI specification."]
+        });
+
+        // Helper function to build the URL
+        sourceFile.addFunction({
+            name: "getServerUrl",
+            isExported: true,
+            parameters: [
+                { name: "indexOrDescription", type: "number | string", initializer: "0" },
+                { name: "variables", type: "Record<string, string>", hasQuestionToken: true }
+            ],
+            returnType: "string",
+            docs: [
+                "Gets the URL for a specific server definition, substituting variables if needed.",
+                "@param indexOrDescription The index of the server in `API_SERVERS` or its description. Defaults to 0.",
+                "@param variables A map of variable names to values to override the defaults.",
+                "@throws Error if the server is not found.",
+                "@returns The fully constructed URL."
+            ],
+            statements: writer => {
+                writer.writeLine("let server: ServerConfiguration | undefined;");
+                writer.writeLine("if (typeof indexOrDescription === 'number') {").indent(() => {
+                    writer.writeLine("server = API_SERVERS[indexOrDescription];");
+                }).writeLine("} else {").indent(() => {
+                    writer.writeLine("server = API_SERVERS.find(s => s.description === indexOrDescription);");
+                }).writeLine("}");
+
+                writer.writeLine("if (!server) {").indent(() => {
+                    writer.writeLine("throw new Error(`Server not found: ${indexOrDescription}`);");
+                }).writeLine("}");
+
+                writer.writeLine("let url = server.url;");
+                writer.writeLine("if (server.variables) {").indent(() => {
+                    writer.writeLine("Object.entries(server.variables).forEach(([key, config]) => {").indent(() => {
+                        writer.writeLine("const value = variables?.[key] ?? config.default;");
+                        writer.writeLine("// Simple substitution (e.g., {port})");
+                        writer.writeLine("url = url.replace(new RegExp(`{${key}}`, 'g'), value);");
+                    }).writeLine("});");
+                }).writeLine("}");
+                writer.writeLine("return url;");
+            }
+        });
+
+        sourceFile.formatText();
+    }
+}

tests/40-emit-utility/09-server-url-generator.spec.ts

@@ -0,0 +1,111 @@
+// tests/40-emit-utility/09-server-url-generator.spec.ts
+
+import { describe, expect, it } from 'vitest';
+import { Project } from 'ts-morph';
+import { SwaggerParser } from '@src/core/parser.js';
+import { ServerUrlGenerator } from '@src/service/emit/utility/server-url.generator.js';
+import { createTestProject } from '../shared/helpers.js';
+import ts from 'typescript';
+
+describe('Emitter: ServerUrlGenerator', () => {
+
+    const runGenerator = (servers: any[]) => {
+        const project = createTestProject();
+        const parser = new SwaggerParser({
+            openapi: '3.0.0',
+            info: { title: 'Test', version: '1.0' },
+            paths: {},
+            servers
+        } as any, { options: {} } as any);
+
+        new ServerUrlGenerator(parser, project).generate('/out');
+        return project;
+    };
+
+    const compileHelper = (project: Project) => {
+        const sourceFile = project.getSourceFileOrThrow('/out/utils/server-url.ts');
+        const startText = sourceFile.getText();
+        // Removing export keywords to evaluate in this context as strict CommonJS/Script
+        const jsCode = ts.transpile(startText.replace(/export /g, ''), {
+            target: ts.ScriptTarget.ESNext,
+            module: ts.ModuleKind.CommonJS
+        });
+        const moduleScope = { API_SERVERS: [], getServerUrl: null as any };
+        // Evaluate in simple scope
+        new Function('scope', `
+            ${jsCode} 
+            scope.API_SERVERS = API_SERVERS; 
+            scope.getServerUrl = getServerUrl; 
+        `)(moduleScope);
+        return moduleScope;
+    };
+
+    it('should not generate file if no servers are defined', () => {
+        const project = runGenerator([]);
+        expect(project.getSourceFile('/out/utils/server-url.ts')).toBeUndefined();
+    });
+
+    it('should generate API_SERVERS constant', () => {
+        const project = runGenerator([
+            { url: 'https://api.example.com', description: 'Production' }
+        ]);
+        const text = project.getSourceFileOrThrow('/out/utils/server-url.ts').getText();
+        expect(text).toContain('export const API_SERVERS: ServerConfiguration[] = [');
+        expect(text).toContain('"url": "https://api.example.com"');
+    });
+
+    it('should generate logic to substitute simple variables', () => {
+        const project = runGenerator([
+            {
+                url: 'https://{env}.example.com/v1',
+                variables: { env: { default: 'dev' } }
+            }
+        ]);
+
+        const { getServerUrl } = compileHelper(project);
+
+        // Use default
+        expect(getServerUrl(0)).toBe('https://dev.example.com/v1');
+        // Override
+        expect(getServerUrl(0, { env: 'prod' })).toBe('https://prod.example.com/v1');
+    });
+
+    it('should generate logic to look up server by description', () => {
+        const project = runGenerator([
+            { url: 'https://dev.api.com', description: 'Development' },
+            { url: 'https://prod.api.com', description: 'Production' }
+        ]);
+
+        const { getServerUrl } = compileHelper(project);
+
+        expect(getServerUrl('Production')).toBe('https://prod.api.com');
+        expect(getServerUrl('Development')).toBe('https://dev.api.com');
+    });
+
+    it('should throw error if server is not found', () => {
+        const project = runGenerator([{ url: '/' }]);
+        const { getServerUrl } = compileHelper(project);
+        expect(() => getServerUrl(99)).toThrow('Server not found: 99');
+        expect(() => getServerUrl('Unknown')).toThrow('Server not found: Unknown');
+    });
+
+    it('should handle multiple variables', () => {
+        const project = runGenerator([
+            {
+                url: '{protocol}://{host}:{port}/{base}',
+                variables: {
+                    protocol: { default: 'https' },
+                    host: { default: 'localhost' },
+                    port: { default: '8080' },
+                    base: { default: 'api' }
+                }
+            }
+        ]);
+        const { getServerUrl } = compileHelper(project);
+
+        // Defaults
+        expect(getServerUrl(0)).toBe('https://localhost:8080/api');
+        // Partial override
+        expect(getServerUrl(0, { port: '3000', protocol: 'http' })).toBe('http://localhost:3000/api');
+    });
+});