Merge pull request #64 from sacconazzo/develop

sacconazzo · web-flow · commit 70c82c962890 · 2025-11-15T17:58:20.000+01:00
v2.3
diff --git a/README.md b/README.md
@@ -71,6 +71,38 @@ components:
 
 For each endpoint extension, you can define OpenAPI partials by adding an `oas.yaml` file in the root of that endpoint's folder.
 
+### Non-bundled extensions
+
+Place the `oas.yaml` file directly in the extension folder:
+
+```
+- ./extensions/
+  ─ oasconfig.yaml (optional)
+  - my-endpoint-extension/
+    - oas.yaml
+```
+
+### Bundled extensions
+
+For bundled extensions, place `oas.yaml` files in each sub-extension's folder under the `src` directory:
+
+```
+- ./extensions/
+  ─ oasconfig.yaml (optional)
+  - my-bundle-extension/
+    - src/
+      - routes-endpoint/
+        - oas.yaml
+      - admin-endpoint/
+        - oas.yaml
+```
+
+This structure follows Directus's standard bundle architecture where each sub-extension (routes, endpoints, hooks, etc.) has its own folder under `src/`. The extension will automatically discover and merge all `oas.yaml` files from these subdirectories.
+
+### Mixed environments
+
+Both bundled and non-bundled extensions can coexist in the same project. The extension will automatically detect and merge all `oas.yaml` files from both types.
+
 Properties:
 
 -   `tags` _optional_ openapi custom tags
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
     "name": "directus-extension-api-docs",
-    "version": "2.2.3",
+    "version": "2.3.0",
     "description": "directus extension for swagger interface and openapi including custom endpoints definitions // custom endpoint validations middleware based on openapi",
     "licence": "MIT",
     "icon": "api",
diff --git a/src/utils.ts b/src/utils.ts
@@ -93,19 +93,43 @@ export function getConfig(): oasConfig {
             config.components = merge(config.components || {}, oas.components || {});
         };
 
+        const scanDirectory = (dirPath: string) => {
+            if (!fs.existsSync(dirPath)) return;
+
+            const files = fs.readdirSync(dirPath, { withFileTypes: true });
+            for (const file of files) {
+                if (!file.isDirectory()) continue;
+
+                const extensionPath = path.join(dirPath, file.name);
+
+                // Check for oas.yaml at root level (non-bundle extensions)
+                const rootOasPath = path.join(extensionPath, 'oas.yaml');
+                if (fs.existsSync(rootOasPath)) {
+                    mergeConfig(rootOasPath);
+                }
+
+                // Check for oas.yaml in src subdirectories (bundled extensions - green option)
+                const srcPath = path.join(extensionPath, 'src');
+                if (fs.existsSync(srcPath)) {
+                    const srcFiles = fs.readdirSync(srcPath, { withFileTypes: true });
+                    for (const srcFile of srcFiles) {
+                        if (srcFile.isDirectory()) {
+                            const bundleOasPath = path.join(srcPath, srcFile.name, 'oas.yaml');
+                            if (fs.existsSync(bundleOasPath)) {
+                                mergeConfig(bundleOasPath);
+                            }
+                        }
+                    }
+                }
+            }
+        };
+
         const extensionsPath = path.join(directusDir(), extensionDir);
-        const files = fs.readdirSync(extensionsPath, { withFileTypes: true });
-        for (const file of files) {
-            const oasPath = `${extensionsPath}/${file.name}/oas.yaml`;
-            if (file.isDirectory() && fs.existsSync(oasPath)) mergeConfig(oasPath);
-        }
+        scanDirectory(extensionsPath);
 
+        // Legacy support for /endpoints subfolder
         const legacyEndpointsPath = path.join(directusDir(), extensionDir, '/endpoints');
-        const legacyFiles = fs.readdirSync(legacyEndpointsPath, { withFileTypes: true });
-        for (const file of legacyFiles) {
-            const oasPath = `${legacyEndpointsPath}/${file.name}/oas.yaml`;
-            if (file.isDirectory() && fs.existsSync(oasPath)) mergeConfig(oasPath);
-        }
+        scanDirectory(legacyEndpointsPath);
 
         return config;
     } catch (e) {
diff --git a/tests/index.test.ts b/tests/index.test.ts
@@ -1,5 +1,5 @@
 import { oasConfig, oas } from '../src/types';
-import { getConfig, getPackage, filterPaths } from '../src/utils';
+import { getConfig, getPackage, filterPaths, merge } from '../src/utils';
 
 describe('openapi config generation', () => {
     afterAll(async () => {
@@ -71,10 +71,19 @@ describe('getPackage', () => {
         expect(test).toHaveProperty('version');
         expect(test).toHaveProperty('description');
     });
+    test('should return empty object when package.json not found', async () => {
+        const originalCwd = process.cwd();
+        jest.spyOn(process, 'cwd').mockImplementation(() => {
+            return '/nonexistent/path';
+        });
+        const test = await getPackage();
+        expect(test).toEqual({});
+        process.cwd = () => originalCwd;
+    });
 });
 
 describe('filterPaths', () => {
-    test('should be valid', () => {
+    test('should filter paths based on published tags', () => {
         const oasConfig: oasConfig = {
             docsPath: 'api-docs',
             info: {},
@@ -113,4 +122,203 @@ describe('filterPaths', () => {
         expect(oas.tags.length).toEqual(1);
         expect(oas.tags[0].name).toEqual('tag2');
     });
+
+    test('should handle empty publishedTags array', () => {
+        const oasConfig: oasConfig = {
+            docsPath: 'api-docs',
+            info: {},
+            useAuthentication: true,
+            tags: [],
+            components: {},
+            publishedTags: [],
+            paths: {},
+        };
+        const oas: oas = {
+            info: {},
+            tags: [{ name: 'tag1' }, { name: 'tag2' }],
+            components: {},
+            paths: {
+                endpoint1: {
+                    get: { tags: ['tag1'] },
+                },
+            },
+        };
+        filterPaths(oasConfig, oas);
+        expect(oas.paths.endpoint1?.get).toBeUndefined();
+        expect(oas.tags.length).toEqual(0);
+    });
+
+    test('should handle endpoints with multiple published tags', () => {
+        const oasConfig: oasConfig = {
+            docsPath: 'api-docs',
+            info: {},
+            useAuthentication: true,
+            tags: [],
+            components: {},
+            publishedTags: ['tag1', 'tag2', 'tag3'],
+            paths: {},
+        };
+        const oas: oas = {
+            info: {},
+            tags: [{ name: 'tag1' }, { name: 'tag2' }, { name: 'tag3' }],
+            components: {},
+            paths: {
+                endpoint1: {
+                    get: { tags: ['tag1', 'tag2', 'tag3'] },
+                },
+            },
+        };
+        filterPaths(oasConfig, oas);
+        expect(oas.paths.endpoint1).toHaveProperty('get');
+        expect(oas.paths.endpoint1?.get?.tags.length).toEqual(3);
+        expect(oas.tags.length).toEqual(3);
+    });
+
+    test('should handle endpoints without tags', () => {
+        const oasConfig: oasConfig = {
+            docsPath: 'api-docs',
+            info: {},
+            useAuthentication: true,
+            tags: [],
+            components: {},
+            publishedTags: ['tag1'],
+            paths: {},
+        };
+        const oas: oas = {
+            info: {},
+            tags: [{ name: 'tag1' }],
+            components: {},
+            paths: {
+                endpoint1: {
+                    get: { tags: [] },
+                },
+            },
+        };
+        filterPaths(oasConfig, oas);
+        expect(oas.paths.endpoint1?.get).toBeUndefined();
+    });
+});
+
+describe('merge', () => {
+    test('should deep merge two simple objects', () => {
+        const obj1 = { a: 1, b: 2 };
+        const obj2 = { b: 3, c: 4 };
+        const result = merge(obj1, obj2);
+        expect(result).toEqual({ a: 1, b: 3, c: 4 });
+    });
+
+    test('should deep merge nested objects', () => {
+        const obj1 = { a: { x: 1, y: 2 }, b: 3 };
+        const obj2 = { a: { y: 3, z: 4 }, c: 5 };
+        const result = merge(obj1, obj2);
+        expect(result).toEqual({ a: { x: 1, y: 3, z: 4 }, b: 3, c: 5 });
+    });
+
+    test('should merge arrays', () => {
+        const obj1 = { arr: [1, 2] };
+        const obj2 = { arr: [3, 4] };
+        const result = merge(obj1, obj2);
+        expect(result.arr).toEqual([3, 4]);
+    });
+
+    test('should handle empty objects', () => {
+        const obj1 = {};
+        const obj2 = { a: 1, b: 2 };
+        const result = merge(obj1, obj2);
+        expect(result).toEqual({ a: 1, b: 2 });
+    });
+
+    test('should merge complex nested structures', () => {
+        const obj1 = {
+            components: {
+                schemas: { User: { type: 'object' } },
+                responses: { 200: { description: 'OK' } },
+            },
+        };
+        const obj2 = {
+            components: {
+                schemas: { Post: { type: 'object' } },
+                parameters: { id: { in: 'path' } },
+            },
+        };
+        const result = merge(obj1, obj2);
+        expect(result.components.schemas).toHaveProperty('User');
+        expect(result.components.schemas).toHaveProperty('Post');
+        expect(result.components.responses).toHaveProperty('200');
+        expect(result.components.parameters).toHaveProperty('id');
+    });
+
+    test('should handle null and undefined values', () => {
+        const obj1 = { a: 1, b: null };
+        const obj2 = { b: 2, c: undefined };
+        const result = merge(obj1, obj2);
+        expect(result).toEqual({ a: 1, b: 2, c: undefined });
+    });
+
+    test('should overwrite primitive values', () => {
+        const obj1 = { a: 'hello', b: 10, c: true };
+        const obj2 = { a: 'world', b: 20 };
+        const result = merge(obj1, obj2);
+        expect(result).toEqual({ a: 'world', b: 20, c: true });
+    });
+});
+
+describe('getConfig edge cases', () => {
+    test('should return default config when no oasconfig exists', () => {
+        jest.spyOn(process, 'cwd').mockImplementation(() => {
+            return './tests/mocks/nonexistent';
+        });
+        const test = getConfig();
+        expect(test.docsPath).toBe('api-docs');
+        expect(test.useAuthentication).toBe(false);
+        expect(test.tags).toEqual([]);
+        expect(test.publishedTags).toEqual([]);
+    });
+
+    test('should handle missing oas.yaml files gracefully', () => {
+        jest.spyOn(process, 'cwd').mockImplementation(() => {
+            return './tests/mocks/oasconfig';
+        });
+        const test = getConfig();
+        expect(test).toBeDefined();
+        expect(test.docsPath).toBeDefined();
+    });
+});
+
+describe('bundled extension support', () => {
+    test('should merge oas.yaml from bundle extension src subdirectories', () => {
+        jest.spyOn(process, 'cwd').mockImplementation(() => {
+            return './tests/mocks/bundle';
+        });
+        const test = getConfig();
+        expect(test).toHaveProperty('docsPath');
+        expect(test).toHaveProperty('tags');
+        expect(test).toHaveProperty('paths');
+        expect(test).toHaveProperty('components');
+
+        // Check that routes from bundled sub-extensions are included
+        expect(test.paths).toHaveProperty('/bundle/items');
+        expect(test.paths).toHaveProperty('/bundle/users');
+
+        // Check that tags from bundled sub-extensions are included
+        expect(test.tags).toEqual(expect.arrayContaining([expect.objectContaining({ name: 'bundle-routes' }), expect.objectContaining({ name: 'bundle-users' })]));
+
+        // Check that components from bundled sub-extensions are included
+        expect(test.components).toHaveProperty('schemas');
+        expect(test.components.schemas).toHaveProperty('BundleItem');
+    });
+
+    test('should merge both bundled and non-bundled extensions', () => {
+        jest.spyOn(process, 'cwd').mockImplementation(() => {
+            return './tests/mocks/mixed';
+        });
+        const test = getConfig();
+
+        // Check that routes from both types are included
+        expect(test.paths).toHaveProperty('/regular/endpoint');
+        expect(test.paths).toHaveProperty('/bundle/route-a');
+
+        // Check that tags from both types are included
+        expect(test.tags).toEqual(expect.arrayContaining([expect.objectContaining({ name: 'regular' }), expect.objectContaining({ name: 'bundle-a' })]));
+    });
 });
diff --git a/tests/mocks/bundle/extensions/my-bundle-extension/src/my-routes/oas.yaml b/tests/mocks/bundle/extensions/my-bundle-extension/src/my-routes/oas.yaml
@@ -0,0 +1,32 @@
+openapi: 3.0.0
+info:
+  title: Bundle Extension API
+  version: 1.0.0
+  description: API from bundled extension
+tags:
+  - name: bundle-routes
+    description: Routes from bundle extension
+paths:
+  /bundle/items:
+    get:
+      tags:
+        - bundle-routes
+      summary: Get items from bundle
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+components:
+  schemas:
+    BundleItem:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
diff --git a/tests/mocks/bundle/extensions/my-bundle-extension/src/user-routes/oas.yaml b/tests/mocks/bundle/extensions/my-bundle-extension/src/user-routes/oas.yaml
@@ -0,0 +1,16 @@
+openapi: 3.0.0
+info:
+  title: Another Bundle Route
+  version: 1.0.0
+tags:
+  - name: bundle-users
+    description: User routes from bundle
+paths:
+  /bundle/users:
+    get:
+      tags:
+        - bundle-users
+      summary: Get users from bundle
+      responses:
+        '200':
+          description: Success
diff --git a/tests/mocks/mixed/extensions/bundle-extension/src/routes-a/oas.yaml b/tests/mocks/mixed/extensions/bundle-extension/src/routes-a/oas.yaml
@@ -0,0 +1,16 @@
+openapi: 3.0.0
+info:
+  title: Bundle Extension Routes A
+  version: 1.0.0
+tags:
+  - name: bundle-a
+    description: Bundled extension route A
+paths:
+  /bundle/route-a:
+    get:
+      tags:
+        - bundle-a
+      summary: Bundle route A
+      responses:
+        '200':
+          description: Success
diff --git a/tests/mocks/mixed/extensions/regular-extension/oas.yaml b/tests/mocks/mixed/extensions/regular-extension/oas.yaml

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "directus-extension-api-docs",`
`3`		`- "version": "2.2.3",`
	`3`	`+ "version": "2.3.0",`
`4`	`4`	`"description": "directus extension for swagger interface and openapi including custom endpoints definitions // custom endpoint validations middleware based on openapi",`
`5`	`5`	`"licence": "MIT",`
`6`	`6`	`"icon": "api",`