directus-extension-api-docs 1.9.7 → 2.0.0

package/README.md

@@ -1,9 +1,13 @@
 # directus-extension-api-docs
 
 Directus Extension to include
-- a Swagger interface
-- custom endpoints definitions
-- custom endpoints data validation based on your definitions
+
+-   a Swagger interface
+-   configurable autogenerated openapi documentation file
+    -- custom endpoint definitions included
+-   validation middleware on your custom endpoints (based on your openapi)
+
+> Compatible with latest versions of Directus and monorepo installation with packaged extension.
 
 ![workspace](assets/swagger.png)
 
@@ -21,11 +25,14 @@ Ref: https://github.com/directus/directus
 
     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)
 
-For include you custom endpoints.
+To include you custom endpoints in your documentation.
 
-Create a `oasconfig.yaml` file under `/extensions/endpoints` folder.
+Create a `oasconfig.yaml` file under `/extensions` folder.
 
 Options:
 
@@ -66,7 +73,7 @@ components:
 
 ## Definitions (optional)
 
-For each custom endpoints group, you can define api's including a file `oas.yaml` in root path of your group folder.
+For each endpoint extension, you can define api's including a file `oas.yaml` in root path of your extension endpoint folder.
 
 Properties:
 
@@ -74,7 +81,7 @@ Properties:
 -   `paths` _optional_ openapi custom paths
 -   `components` _optional_ openapi custom components
 
-Exemple below (`./extensions/endpoints/my-custom-path/oas.yaml`) :
+Exemple below (`./extensions/my-endpoint-extensions/oas.yaml`) :
 
 ```
 tags:
@@ -115,31 +122,44 @@ components:
       type: object # ref to standard components declaring it empty
 ```
 
+### Legacy mode
+
+Configuration and definitions can also be managed in this structure:
+
+```
+- ./extensions/
+  - endpoints/
+    - oasconfig.yaml
+    - my-endpoint-extensions/
+      - oas.yaml
+    - my-endpoint-extensions2/
+      - oas.yaml
+```
+
 ## Validations (optional)
 
 You can enable a request validations middleware based on your custom definitions.
 
-Call `validate` function inside your custom endpoint registration.
+Call `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.
 
 Example below:
 
 ```
-const { validate } = require('directus-extension-api-docs');
-
-const id = 'my-custom-path';
+const { validate } = require('directus-extension-api-docs')
 
-module.exports = {
-    id,
-    handler: async function registerEndpoint(router, { services, getSchema }) {
+const id = 'my-custom-path'
 
+export default {
+    id: 'info',
+    handler: async (router, { services, getSchema }) => {
         const schema = await getSchema();
         await validate(router, services, schema); // Enable validator
 
         router.post('/my-endpoint', async (req, res, next) => {
             ...
-        });
+        })
     },
-};
+}
 ```