Merge pull request #73 from aligent/fix/MI-275-nx-openapi-improvement

MI-275: Added couple of improvements to nx-openapi generator

Author: kai-nguyen-aligent

packages/nx-openapi/src/generators/client/client-specific-files/README.md.template

@@ -1,23 +1,53 @@
-// The following is an example file generated to demonstrate how to use your newly generated types
-import { paths } from './types';
-import createClient from 'openapi-fetch';
+/**
+ * Example client demonstrating how to use the generated API types.
+ * Adjust middlewares usage according to your need.
+ *
+ * - Check out Aligent's middlewares: https://github.com/aligent/microservice-development-utilities
+ * - For more information about openapi-fetch middlewares: https://openapi-ts.dev/openapi-fetch/middleware-auth#middleware
+ */
+import {
+    apiKeyAuthMiddleware,
+    fetchSsmParams,
+    retryMiddleware,
+} from '@aligent/microservice-util-lib';
+import createClient, { Client, ClientOptions } from 'openapi-fetch';
+import { paths } from './generated-types';
 
-// This type is an example of what is initialised using the types generated in the paths interface which is created when generation occurs.
-// Its worth looking into that paths interface, to see the the types that were generated for your client.
-type ExampleResponse =
-    paths['/customers']['get']['responses']['200']['content']['application/json'];
+export class <%= className %> {
+    private credential: string | null = null;
+    public readonly client: Client<paths, `${string}/${string}`>;
 
-// Using openapi-fetch we can create a fully typed REST client by passing in paths as a generic.
-// If you wish however, you can use any api client you want (axios, basic fetch etc.) and use the paths separately to maintain type safety in your client.
-// Keep this variable exported. It will need to be to make sure all other services in your application can access and use the client.
-export const client = createClient<paths>({
-    baseUrl: '',
-    signal: AbortSignal.timeout(10000),
-});
+    constructor(options: ClientOptions, credentialPath: string) {
+        this.client = createClient<paths>(options);
 
-// Client getters are then fully typed. Try deleting '/customers' and seeing what routes you can use!
-const response = client.GET('/customers', {
-    params: {
-        query: {},
-    },
-});
+        /**
+         * The order in which middleware are registered matters.
+         * - For requests, onRequest() will be called in the order registered
+         * - For responses, onResponse() will be called in reverse order.
+         */
+        this.client.use(
+            apiKeyAuthMiddleware({
+                header: 'Authorization',
+                value: async () => {
+                    if (!this.credential) {
+                        const param = await fetchSsmParams(credentialPath);
+                        if (!param?.Value) {
+                            throw new Error('Unable to fetch API client credential');
+                        }
+
+                        this.credential = param.Value;
+                    }
+
+                    return `Bearer ${this.credential}`;
+                },
+            })
+        );
+
+        this.client.use(
+            retryMiddleware({
+                onRetry: ({ attempt, error }) =>
+                    console.log(`Retrying...${attempt} due to ${String(error)}`),
+            })
+        );
+    }
+}

packages/nx-openapi/src/generators/client/client-specific-files/client.ts.template

@@ -0,0 +1,29 @@
+# Generated OpenAPI REST API Clients
+
+This folder contains TypeScript API clients generated from OpenAPI specifications using Nx generators and `openapi-typescript`. Each client exposes strongly typed request and response types under `generated-types` and a ready-to-use `openapi-fetch` client class.
+
+## Usage
+- Import the generated client into your code.
+- Instantiate the client with appropriate ClientOptions (base URL, fetch implementation, etc.) and call the typed endpoints.
+
+## Example
+```typescript
+import { MyApiClient } from '@clients'; // Adjust the import name as necessary
+
+const client = new MyApiClient(
+    { baseUrl: 'https://my-api-client.base-url', signal: AbortSignal.timeout(30000) },
+    '/my/api/client/access-token/path'
+).client;
+
+// Example of calling a typed endpoint
+async function fetchData() {
+    try {
+        const response = await client.GET('/path/to/endpoint'); // Replace with actual endpoint method
+        console.log(response);
+    } catch (error) {
+        console.error('Error fetching data:', error);
+    }
+}
+
+fetchData();
+```

packages/nx-openapi/src/generators/client/files/README.md.template

@@ -0,0 +1,3 @@
+import baseConfig from '../eslint.config.mjs';
+
+export default [...baseConfig];

packages/nx-openapi/src/generators/client/files/eslint.config.mjs.template

@@ -8,6 +8,7 @@ import {
     addTsConfigPath,
     appendToIndexFile,
     attemptToAddProjectConfiguration,
+    toClassName,
 } from '../../helpers/utilities';
 import { ClientGeneratorSchema } from './schema';
 
@@ -45,28 +46,26 @@ export async function clientGenerator(tree: Tree, options: ClientGeneratorSchema
     await generateOpenApiTypes(tree, schemaDest, typesDest);
 
     if (isNewProject) {
-        logger.info('No clients currently exist. Generating a clients folder...');
         logger.info(`Creating new project at ${projectRoot}`);
 
-        // Generate other files
         generateFiles(tree, joinPathFragments(__dirname, './files'), projectRoot, options);
-
-        // Add the project to the tsconfig paths so it can be imported by namespace
         addTsConfigPath(tree, importPath, [joinPathFragments(projectRoot, './src', 'index.ts')]);
     }
 
     // Generate the files for the specific new client
-    generateFiles(
-        tree,
-        joinPathFragments(__dirname, './client-specific-files'),
-        apiClientDest,
-        options
-    );
+    generateFiles(tree, joinPathFragments(__dirname, './client-specific-files'), apiClientDest, {
+        className: toClassName(name),
+    });
 
     // Append to index file for imports
     appendToIndexFile(tree, projectRoot, name);
 
     await formatFiles(tree);
+
+    logger.info(`Successfully generated ${name} API client`);
+    logger.info(
+        `Next step: Run "nx affected -t lint" to fix any linting issues that may arise from the generated code.`
+    );
 }
 
 export default clientGenerator;

packages/nx-openapi/src/generators/client/generator.ts

@@ -6,6 +6,7 @@
     "properties": {
         "name": {
             "type": "string",
+            "pattern": "^[a-z0-9-]+$",
             "description": "Name of the api client.",
             "$default": {
                 "$source": "argv",

packages/nx-openapi/src/generators/client/schema.json

@@ -82,7 +82,6 @@ export async function copySchema(
 export async function validateSchema(path: string): Promise<boolean> {
     let hasError = false;
     try {
-        // TODO: MI-203 - Support private schema endpoint
         const config = await loadConfig();
         const results = await lint({ ref: path, config });
 

packages/nx-openapi/src/helpers/generate-openapi-types.ts

@@ -9,7 +9,7 @@ import { addProjectConfiguration, Tree, updateJson } from '@nx/devkit';
  * @param {Tree} tree - The file system tree representing the current project.
  * @param {string} name - The name of the project to add.
  * @param {string} projectRoot - The root directory of the project.
- * @returns {boolean} `true` if the project configuration was added successfully, `false` if the project already exists.
+ * @returns - Whether project configuration was added successfully, or it already exists.
  * @throws {Error} If an error occurs that is not related to the project already existing.
  */
 export function attemptToAddProjectConfiguration(tree: Tree, projectRoot: string) {
@@ -86,8 +86,24 @@ export function addTsConfigPath(tree: Tree, importPath: string, lookupPaths: str
  */
 export function appendToIndexFile(tree: Tree, projectRoot: string, clientName: string) {
     const indexPath = `${projectRoot}/src/index.ts`;
-    const newLine = `\nexport * as ${clientName}Client from "./${clientName}/client";`;
+    const newLine = `export * from "./${clientName}/client";\n`;
 
     const indexContent = tree.read(indexPath, 'utf-8');
     tree.write(indexPath, indexContent + newLine);
 }
+
+/**
+ * Convert a lower-case alphanumeric string (may include hyphens) into a PascalCase string.
+ *
+ * @param input - The input string to convert.
+ * @example:
+ *  - "my-client" -> "MyClient"
+ */
+export function toClassName(input: string): string {
+    return input
+        .trim()
+        .toLowerCase()
+        .split('-')
+        .map(c => c.charAt(0).toUpperCase() + c.slice(1))
+        .join('');
+}