Merge pull request #61 from sacconazzo/develop

granular publication based on access policy

Author: sacconazzo

README.md

@@ -2,47 +2,47 @@
 
 > Compatible with latest Directus versions and packaged extensions.
 
-Directus Extension to include:
+Directus Extension providing:
 
--   a Swagger interface
--   configurable autogenerated openapi specifications file
-    -- including custom endpoints definitions
--   validation middleware on your custom endpoints (based on your openapi specifications). See below for details
+-   a Swagger UI interface (OpenAPI 3.x)
+-   an autogenerated OpenAPI specification file (merged core + your custom endpoints)
+    -- including custom endpoint definitions
+-   optional validation middleware for your custom endpoints (based on merged OpenAPI spec). See details below
 
 ![workspace](assets/swagger.png)
 
 ## Prerequisites
 
-Working in a Directus nodejs project
+You must already have a Directus Node.js project running.
 
 Ref: https://github.com/directus/directus
 
 ## Installation
 
-    npm install directus-extension-api-docs
+npm install directus-extension-api-docs
 
 -   Swagger interface: by default `http://localhost:8055/api-docs`
 -   Openapi documentation: by default `http://localhost:8055/api-docs/oas`
 
 ## Configuration (optional)
 
-To include you custom endpoints in your documentation.
-
-Create a `oasconfig.yaml` file under `/extensions` folder.
+To include your custom endpoints in the documentation, create an `oasconfig.yaml` file directly under the `/extensions` folder (recommended structure). Avoid placing it under `/extensions/endpoints` unless using Legacy mode.
 
 Options:
 
--   `docsPath` _optional_ path where the interface will be (default 'api-docs')
+-   `docsPath` _optional_ interface base path (default 'api-docs'). Resulting URLs: `/<docsPath>` and `/<docsPath>/oas`.
 -   `info` _optional_ openapi server info (default extract from package.json)
 -   `tags` _optional_ openapi custom tags (will be merged with all standard and all customs tags)
--   `publishedTags` _optional_ if specified, will be published definitions only for specified tags
--   `paths` _optional_ openapi custom paths (will be merged with all standard and all customs paths)
--   `components` _optional_ openapi custom components (will be merged with all standard and all customs tags)
+-   `publishedTags` _optional_ if specified, only operations containing at least one of these tags are kept; all other paths and unused tags are removed.
+-   `paths` _optional_ custom path objects keyed by full path (e.g. `/my-custom-path/my-endpoint`). These are merged into Directus core paths.
+-   `components` _optional_ custom components (schemas, securitySchemes, etc.) shallow-merged over core components.
+-   `useAuthentication` _optional_ (default false). When true, `/api-docs` and `/api-docs/oas` stay publicly reachable: without valid auth they list only anonymous/public paths (no custom endpoints); with auth they list only paths permitted to that user under Directus Access Policies and custom endpoints.
 
 Example below:
 
 ```
 docsPath: 'api-docs'
+useAuthentication: true
 info:
   title: my-directus-bo
   version: 1.5.0
@@ -69,15 +69,15 @@ components:
 
 ## Definitions (optional)
 
-For each endpoint extension, you can define api's including a file `oas.yaml` in root path of your extension endpoint folder.
+For each endpoint extension, you can define OpenAPI partials by adding an `oas.yaml` file in the root of that endpoint's folder.
 
 Properties:
 
 -   `tags` _optional_ openapi custom tags
 -   `paths` _optional_ openapi custom paths
 -   `components` _optional_ openapi custom components
 
-Exemple below (`./extensions/my-endpoint-extensions/oas.yaml`) :
+Example below (`./extensions/my-endpoint-extensions/oas.yaml`):
 
 ```
 tags:
@@ -127,7 +127,7 @@ components:
 
 ### Legacy mode
 
-Configuration and definitions can also be managed in this structure:
+Configuration and definitions can also be managed in this legacy structure (still supported, but prefer the simplified root placement):
 
 ```
 - ./extensions/
@@ -141,11 +141,11 @@ Configuration and definitions can also be managed in this structure:
 
 ## Validations (optional)
 
-You can enable a request validations middleware based on your custom definitions.
+You can enable a request validation middleware based on your merged custom definitions.
 
-Call `validate` function inside your custom endpoint source (`./extensions/my-endpoint-extensions/src/index.js`).
+Call the `validate` function inside your custom endpoint source (`./extensions/my-endpoint-extensions/src/index.js`).
 
-Pass your `router`, `services`, `schema` and a list (_optional_) of endpoints you want to validate.
+Arguments: `validate(router, services, schema, paths?)`. `paths` (optional array) lets you restrict validation to only specific path keys from `oasconfig.yaml` instead of all custom paths.
 
 Example below:
 

package.json

@@ -1,6 +1,6 @@
 {
     "name": "directus-extension-api-docs",
-    "version": "2.1.16",
+    "version": "2.2.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/index.ts

@@ -3,7 +3,7 @@ import { defineEndpoint } from '@directus/extensions-sdk';
 // import { SchemaOverview } from '@directus/shared/types';
 import { SchemaOverview } from '@directus/types';
 import { Router, Request, Response, NextFunction } from 'express';
-import { getConfig, getOas, getPackage, merge, filterPaths } from './utils';
+import { getConfig, getOas, getOasAll, getPackage, merge, filterPaths } from './utils';
 
 const swaggerUi = require('swagger-ui-express');
 const OpenApiValidator = require('express-openapi-validator');
@@ -14,7 +14,7 @@ const id = config.docsPath;
 
 async function validate(router: Router, services: any, schema: SchemaOverview, paths: Array<string>): Promise<Router> {
     if (config?.paths) {
-        const oas = await getOas(services, schema);
+        const oas = await getOasAll(services, schema);
 
         // replace with custom endpoints
         if (paths) {
@@ -65,10 +65,13 @@ export default {
         router.use('/', swaggerUi.serve);
         router.get('/', swaggerUi.setup({}, options));
 
-        router.get('/oas', async (_req: Request, res: Response, next: NextFunction) => {
+        router.get('/oas', async (req: Request, res: Response, next: NextFunction) => {
             try {
                 const schema = await getSchema();
-                const swagger = await getOas(services, schema);
+
+                const accountability = config.useAuthentication ? (req as any).accountability : { admin: true };
+
+                const swagger = await getOas(services, schema, accountability);
 
                 const pkg = await getPackage();
 
@@ -77,22 +80,24 @@ export default {
                 swagger.info.description = config.info.description || pkg?.description || swagger.info.description;
 
                 // inject custom-endpoints
-                try {
-                    for (const path in config.paths) {
-                        swagger.paths[path] = config.paths[path];
+                if (accountability.admin || accountability.user) {
+                    try {
+                        for (const path in config.paths) {
+                            swagger.paths[path] = config.paths[path];
+                        }
+
+                        for (const tag of config.tags) {
+                            swagger.tags.push(tag);
+                        }
+
+                        swagger.components = merge(config.components, swagger.components);
+                    } catch (e) {
+                        logger.info('No custom definitions');
                     }
 
-                    for (const tag of config.tags) {
-                        swagger.tags.push(tag);
-                    }
-
-                    swagger.components = merge(config.components, swagger.components);
-                } catch (e) {
-                    logger.info('No custom definitions');
+                    if (config.publishedTags?.length) filterPaths(config, swagger);
                 }
 
-                if (config.publishedTags?.length) filterPaths(config, swagger);
-
                 res.json(swagger);
             } catch (error: any) {
                 return next(new Error(error.message || error[0].message));

src/types.ts

@@ -3,6 +3,7 @@ export interface oasConfig {
     info: any;
     tags: Array<any>;
     publishedTags: Array<string>;
+    useAuthentication: boolean;
     paths: {
         [key: string]: any;
     };

src/utils.ts

@@ -26,6 +26,7 @@ function getConfigRoot(): oasConfig {
         info: {},
         tags: [],
         publishedTags: [],
+        useAuthentication: false,
         paths: {},
         components: {},
     };
@@ -43,6 +44,8 @@ function getConfigRoot(): oasConfig {
         config.docsPath = config.docsPath || defConfig.docsPath;
         config.info = config.info || defConfig.info;
         config.tags = config.tags || defConfig.tags;
+        config.publishedTags = config.publishedTags || defConfig.publishedTags;
+        config.useAuthentication = typeof config.useAuthentication === 'boolean' ? config.useAuthentication : defConfig.useAuthentication;
         config.paths = config.paths || defConfig.paths;
         config.components = config.components || defConfig.components;
         return config;
@@ -110,12 +113,12 @@ export function getConfig(): oasConfig {
     }
 }
 
-export async function getOas(services: any, schema: SchemaOverview): Promise<oas> {
+export async function getOasAll(services: any, schema: SchemaOverview): Promise<oas> {
     if (oasBuffer) return JSON.parse(oasBuffer);
 
     const { SpecificationService } = services;
     const service = new SpecificationService({
-        accountability: { admin: true }, // null or accountability.admin = true needed
+        accountability: { admin: true },
         schema,
     });
 
@@ -124,6 +127,18 @@ export async function getOas(services: any, schema: SchemaOverview): Promise<oas
     return JSON.parse(oasBuffer);
 }
 
+export async function getOas(services: any, schema: SchemaOverview, accountability: any): Promise<oas> {
+    const { SpecificationService } = services;
+    const service = new SpecificationService({
+        accountability,
+        schema,
+    });
+
+    const oas = JSON.stringify(await service.oas.generate());
+
+    return JSON.parse(oas);
+}
+
 export async function getPackage() {
     try {
         const workspaceDir = await findWorkspaceDir('.');

tests/index.test.ts

@@ -78,6 +78,7 @@ describe('filterPaths', () => {
         const oasConfig: oasConfig = {
             docsPath: 'api-docs',
             info: {},
+            useAuthentication: true,
             tags: [],
             components: {},
             publishedTags: ['tag2'],