upd. documentation

Author: sacconazzo

README.md

@@ -2,43 +2,41 @@
 
 > 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)
--   `useAuthentication` _optional_ (default false). When enabled, access to `/api-docs` and `/api-docs/oas` requires a Directus admin cookie, static token, or Bearer JWT. Authorization is applied per endpoint based on Directus Access Policies, ensuring users only see endpoints they are allowed to access.
+-   `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:
 
@@ -71,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:
@@ -129,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/
@@ -143,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:
 

tests/index.test.ts

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