Merge pull request #63 from sacconazzo/sacconazzo/issue22

Authorize does not work and custom endpoints within bundle extensions

Author: sacconazzo

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

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",

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) {

tests/index.test.ts

@@ -284,3 +284,41 @@ describe('getConfig edge cases', () => {
         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' })]));
+    });
+});

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

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

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

tests/mocks/mixed/extensions/regular-extension/oas.yaml

@@ -0,0 +1,16 @@
+openapi: 3.0.0
+info:
+  title: Regular Extension API
+  version: 1.0.0
+tags:
+  - name: regular
+    description: Regular non-bundled extension
+paths:
+  /regular/endpoint:
+    get:
+      tags:
+        - regular
+      summary: Regular extension endpoint
+      responses:
+        '200':
+          description: Success