@aligent/nx-openapi 0.1.2 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aligent/nx-openapi",
-  "version": "0.1.2",
+  "version": "1.0.0",
   "type": "commonjs",
   "main": "./src/index.js",
   "typings": "./src/index.d.ts",

package/src/generators/client/client-specific-files/client.ts.template

@@ -0,0 +1,53 @@
+/**
+ * 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';
+
+export class <%= className %> {
+    private credential: string | null = null;
+    public readonly client: Client<paths, `${string}/${string}`>;
+
+    constructor(options: ClientOptions, credentialPath: string) {
+        this.client = createClient<paths>(options);
+
+        /**
+         * 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)}`),
+            })
+        );
+    }
+}

package/src/generators/client/files/README.md.template

@@ -1 +1,29 @@
-The <%= name %> REST API Client was generated using Nx Generators and openapi-typescript codegen
+# 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();
+```

package/src/generators/client/files/eslint.config.mjs.template

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

package/src/generators/client/files/src/index.ts.template

@@ -1,22 +1 @@
-// The following is an example file generated to demonstrate how to use your newly generated types
-import { paths } from '../generated';
-import createClient from 'openapi-fetch';
-
-// 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'];
-
-// 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.
-const client = createClient<paths>({
-    baseUrl: '',
-    signal: AbortSignal.timeout(10000),
-});
-
-// Client getters are then fully typed. Try deleting '/customers' and seeing what routes you can use!
-const response = client.GET('/customers', {
-    params: {
-        query: {},
-    },
-});
+// When a client is generated, its added as an export to this index file. This makes sure that your entire application has access to all of your clients.

package/src/generators/client/files/tsconfig.json.template

@@ -1,5 +1,5 @@
 {
-    "extends": "../../tsconfig.base.json",
+    "extends": "../tsconfig.base.json",
     "compilerOptions": {
         "forceConsistentCasingInFileNames": true,
         "strict": true,

package/src/generators/client/generator.js

@@ -6,7 +6,7 @@ const generate_openapi_types_1 = require("../../helpers/generate-openapi-types")
 const utilities_1 = require("../../helpers/utilities");
 const VALID_EXTENSIONS = ['yaml', 'yml', 'json'];
 async function clientGenerator(tree, options) {
-    const { name, schemaPath, importPath = `@clients/${name}`, skipValidate, override } = options;
+    const { name, schemaPath, importPath = `@clients`, skipValidate, override } = options;
     const ext = schemaPath.split('.').pop() || '';
     if (!VALID_EXTENSIONS.includes(ext)) {
         throw new Error(`Invalid schema file extension: ${ext}`);
@@ -17,23 +17,29 @@ async function clientGenerator(tree, options) {
             throw new Error('Schema validation failed!');
         }
     }
-    const projectRoot = `clients/${name}`;
-    const schemaDest = `${projectRoot}/schema.${ext}`;
-    const typesDest = `${projectRoot}/generated/index.ts`;
-    const isNewProject = (0, utilities_1.attemptToAddProjectConfiguration)(tree, name, projectRoot);
-    if (!isNewProject && !override) {
-        devkit_1.logger.info(`Project ${name} already exists. Use --override to override the existing schema.`);
-        return;
+    const projectRoot = `clients`;
+    const apiClientDest = `${projectRoot}/src/${name}`;
+    const schemaDest = `${apiClientDest}/schema.${ext}`;
+    const typesDest = `${apiClientDest}/generated-types.ts`;
+    if (!override && tree.exists(apiClientDest)) {
+        throw new Error(`Directory "${name}" already exists. If you want to override the current api client in this directory use "--override"`);
     }
+    const isNewProject = (0, utilities_1.attemptToAddProjectConfiguration)(tree, projectRoot);
     await (0, generate_openapi_types_1.copySchema)(tree, schemaDest, schemaPath);
     await (0, generate_openapi_types_1.generateOpenApiTypes)(tree, schemaDest, typesDest);
     if (isNewProject) {
         devkit_1.logger.info(`Creating new project at ${projectRoot}`);
-        // Generate other files
         (0, devkit_1.generateFiles)(tree, (0, devkit_1.joinPathFragments)(__dirname, './files'), projectRoot, options);
-        // Add the project to the tsconfig paths so it can be imported by namespace
         (0, utilities_1.addTsConfigPath)(tree, importPath, [(0, devkit_1.joinPathFragments)(projectRoot, './src', 'index.ts')]);
     }
+    // Generate the files for the specific new client
+    (0, devkit_1.generateFiles)(tree, (0, devkit_1.joinPathFragments)(__dirname, './client-specific-files'), apiClientDest, {
+        className: (0, utilities_1.toClassName)(name),
+    });
+    // Append to index file for imports
+    (0, utilities_1.appendToIndexFile)(tree, projectRoot, name);
     await (0, devkit_1.formatFiles)(tree);
+    devkit_1.logger.info(`Successfully generated ${name} API client`);
+    devkit_1.logger.info(`Next step: Run "nx affected -t lint" to fix any linting issues that may arise from the generated code.`);
 }
 exports.default = clientGenerator;

package/src/generators/client/schema.json

@@ -6,6 +6,7 @@
     "properties": {
         "name": {
             "type": "string",
+            "pattern": "^[a-z0-9-]+$",
             "description": "Name of the api client.",
             "$default": {
                 "$source": "argv",
@@ -37,7 +38,7 @@
         },
         "override": {
             "type": "boolean",
-            "description": "Override existing project schema",
+            "description": "Override existing files during generation",
             "default": false
         }
     },

package/src/helpers/generate-openapi-types.js

@@ -103,7 +103,6 @@ async function copySchema(tree, destination, schemaPath) {
 async function validateSchema(path) {
     let hasError = false;
     try {
-        // TODO: MI-203 - Support private schema endpoint
         const config = await (0, openapi_core_1.loadConfig)();
         const results = await (0, openapi_core_1.lint)({ ref: path, config });
         results.forEach(result => {

package/src/helpers/utilities.d.ts

@@ -8,10 +8,10 @@ import { Tree } 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 declare function attemptToAddProjectConfiguration(tree: Tree, name: string, projectRoot: string): boolean;
+export declare function attemptToAddProjectConfiguration(tree: Tree, projectRoot: string): boolean;
 /**
  * Adds a new path mapping to the `paths` property in the root TypeScript configuration file.
  *
@@ -24,3 +24,21 @@ export declare function attemptToAddProjectConfiguration(tree: Tree, name: strin
  * @throws {Error} If the import path already exists in the `paths` property.
  */
 export declare function addTsConfigPath(tree: Tree, importPath: string, lookupPaths: string[]): void;
+/**
+ * Appends a new export statement to the index file.
+ *
+ * This function reads the content of the index file and appends a new export statement
+ * for the specified client.
+ *
+ * @param {Tree} tree - The file system tree representing the current project.
+ * @param {string} clientName - The name of the client to export.
+ */
+export declare function appendToIndexFile(tree: Tree, projectRoot: string, clientName: string): void;
+/**
+ * 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 declare function toClassName(input: string): string;

package/src/helpers/utilities.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.attemptToAddProjectConfiguration = attemptToAddProjectConfiguration;
 exports.addTsConfigPath = addTsConfigPath;
+exports.appendToIndexFile = appendToIndexFile;
+exports.toClassName = toClassName;
 const devkit_1 = require("@nx/devkit");
 /**
  * Attempts to add a new project configuration to the workspace.
@@ -12,17 +14,17 @@ const devkit_1 = require("@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.
  */
-function attemptToAddProjectConfiguration(tree, name, projectRoot) {
+function attemptToAddProjectConfiguration(tree, projectRoot) {
     try {
-        (0, devkit_1.addProjectConfiguration)(tree, name, {
+        (0, devkit_1.addProjectConfiguration)(tree, 'clients', {
             root: projectRoot,
             projectType: 'library',
             sourceRoot: `${projectRoot}/src`,
             targets: {},
-            tags: ['client', name],
+            tags: ['clients'],
         });
         return true;
     }
@@ -69,3 +71,33 @@ function addTsConfigPath(tree, importPath, lookupPaths) {
         return json;
     });
 }
+/**
+ * Appends a new export statement to the index file.
+ *
+ * This function reads the content of the index file and appends a new export statement
+ * for the specified client.
+ *
+ * @param {Tree} tree - The file system tree representing the current project.
+ * @param {string} clientName - The name of the client to export.
+ */
+function appendToIndexFile(tree, projectRoot, clientName) {
+    const indexPath = `${projectRoot}/src/index.ts`;
+    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"
+ */
+function toClassName(input) {
+    return input
+        .trim()
+        .toLowerCase()
+        .split('-')
+        .map(c => c.charAt(0).toUpperCase() + c.slice(1))
+        .join('');
+}