directus-extension-api-docs 1.4.1 → 1.4.3

package/README.md

@@ -1,134 +1,126 @@
-# directus-extension-api-docs
-
-Directus Extension to include a Swagger interface and custom endpoints definitions
-
-![workspace](assets/swagger.png)
-
-All directus endpoints are autogenerated on runtime.
-
-**You can enable validations middleware based on your custom definitions. See below**
-
-## Prerequisites
-
-Working in a Directus nodejs project
-
-Ref: https://github.com/directus/directus
-
-## Installation
-
-    npm install directus-extension-api-docs
-
-## Configuration (optional)
-
-For include you custom endpoints.
-
-Create a `oasconfig.yaml` file under `/extensions/endpoints` folder.
-
-Options:
-
--   `docsPath` _optional_ path where the interface will be (default 'api-docs')
--   `tags` _optional_ openapi custom tags (will be merged with all standard and all customs 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)
-
-Example below:
-
-```
-docsPath: 'api-docs'
-tags:
-- name: MyCustomTag
-  description: MyCustomTag description
-components:
-  schemas:
-    UserId:
-      type: object
-      required:
-      - user_id
-      x-collection: directus_users
-      properties:
-        user_id:
-          description: Unique identifier for the user.
-          example: 63716273-0f29-4648-8a2a-2af2948f6f78
-          type: string
-
-```
-
-## Definitions (optional)
-
-For each custom endpoints group, you can define api's including a file `oas.yaml` in root path of your group folder.
-
-Properties:
-
--   `tags` _optional_ openapi custom tags
--   `paths` _optional_ openapi custom paths
--   `components` _optional_ openapi custom components
-
-Exemple below (`./extensions/endpoints/my-custom-path/oas.yaml`) :
-
-```
-tags:
-- name: MyCustomTag2
-  description: MyCustomTag description2
-paths:
-  "/my-custom-path/my-endpoint":
-    post:
-      summary: Validate email
-      description: Validate email
-      tags:
-        - MyCustomTag2
-        - MyCustomTag
-      requestBody:
-        content:
-          application/json:
-            schema:
-              "$ref": "#/components/schemas/UserId"
-      responses:
-        '200':
-          description: Successful request
-          content:
-            application/json:
-              schema:
-                "$ref": "#/components/schemas/Users"
-        '401':
-          description: Unauthorized
-          content: {}
-        '422':
-          description: Unprocessable Entity
-          content: {}
-        '500':
-          description: Server Error
-          content: {}
-components:
-  schemas:
-    Users:
-      type: object   # you can ref to standard components declaring it empty
-```
-
-## Validations (optional)
-
-You can enable a request validations middleware based on your custom definitions.
-
-Call `validate` function inside your custom endpoint registration.
-
-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';
-
-module.exports = {
-    id,
-    handler: async function registerEndpoint(router, { services, getSchema }) {
-
-        const schema = await getSchema();
-        await validate(router, services, schema); // Enable validator for custom endpoints
-
-        router.post('/my-endpoint', async (req, res, next) => {
-            ...
-        });
-    },
-};
-```
+# directus-extension-api-docs
+
+Directus Extension to include a Swagger interface and custom endpoints definitions
+
+![workspace](assets/swagger.png)
+
+All directus endpoints are autogenerated on runtime.
+
+**You can enable validations middleware based on your custom definitions. See below**
+
+## Prerequisites
+
+Working in a Directus nodejs project
+
+Ref: https://github.com/directus/directus
+
+## Installation
+
+    npm install directus-extension-api-docs
+
+## Configuration (optional)
+
+For include you custom endpoints.
+
+Create a `oasconfig.yaml` file under `/extensions/endpoints` folder.
+
+Options:
+
+-   `docsPath` _optional_ path where the interface will be (default 'api-docs')
+-   `tags` _optional_ openapi custom tags (will be merged with all standard and all customs 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)
+
+Example below:
+
+```
+docsPath: 'api-docs'
+tags:
+- name: MyCustomTag
+  description: MyCustomTag description
+components:
+  schemas:
+    UserId:
+      type: object
+      required:
+      - user_id
+      x-collection: directus_users
+      properties:
+        user_id:
+          description: Unique identifier for the user.
+          example: 63716273-0f29-4648-8a2a-2af2948f6f78
+          type: string
+
+```
+
+## Definitions (optional)
+
+For each custom endpoints group, you can define api's including a file `oas.yaml` in the root path of your group folder.
+
+Properties:
+
+-   `tags` _optional_ openapi custom tags
+-   `paths` _optional_ openapi custom paths
+-   `components` _optional_ openapi custom components
+
+Exemple below (`./extensions/endpoints/my-custom-path/oas.yaml`) :
+
+```
+tags:
+- name: MyCustomTag2
+  description: MyCustomTag description2
+paths:
+  "/my-custom-path/my-endpoint":
+    post:
+      tags:
+        - MyCustomTag2
+        - MyCustomTag
+      requestBody:
+        content:
+          application/json:
+            schema:
+              "$ref": "#/components/schemas/UserId"
+      responses:
+        '200':
+          description: Successful request
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Users"
+        '401':
+          description: Unauthorized
+          content: {}
+components:
+  schemas:
+    Users:
+      type: object # ref to standard components declaring it empty
+```
+
+## Validations (optional)
+
+You can enable a request validations middleware based on your custom definitions.
+
+Call `validate` function inside your custom endpoint registration.
+
+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';
+
+module.exports = {
+    id,
+    handler: async function registerEndpoint(router, { services, getSchema }) {
+
+        const schema = await getSchema();
+        await validate(router, services, schema); // Enable validator
+
+        router.post('/my-endpoint', async (req, res, next) => {
+            ...
+        });
+    },
+};
+```

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import { Router } from 'express';
+declare function validate(router: Router, services: any, schema: any, paths: Array<string>): Promise<Router>;
+declare const _default: {
+    id: string;
+    validate: typeof validate;
+    handler: any;
+};
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAmC,MAAM,SAAS,CAAC;AAWlE,iBAAe,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAsCzG;;;;;;AAED,wBAiDE"}

package/dist/index.js

@@ -1 +1 @@
-"use strict";const e=require("js-yaml"),s=require("path"),n=require("fs"),t=process.cwd();let o;async function i(e,s){if(o)return JSON.parse(o);const{SpecificationService:n}=e,t=new n({accountability:{admin:!0},schema:s});return o=JSON.stringify(await t.oas.generate()),JSON.parse(o)}function a(e,s){return Object.entries(s).reduce(((e,[s,n])=>(e[s]=n&&"object"==typeof n?a(e[s]=e[s]||(Array.isArray(n)?[]:{}),n):n,e)),e)}const r=require("swagger-ui-express"),c=require("express-openapi-validator"),{findWorkspaceDir:p}=require("@pnpm/find-workspace-dir"),u=function(){try{const o=s.join(t,"./extensions/endpoints/oasconfig.yaml"),i=e.load(n.readFileSync(o,{encoding:"utf-8"})),r=s.join(t,"./extensions/endpoints"),c=n.readdirSync(r,{withFileTypes:!0});for(const s of c){const t=`${r}/${s.name}/oas.yaml`;if(s.isDirectory()&&n.existsSync(t)){const s=e.load(n.readFileSync(t,{encoding:"utf-8"}));i.tags=[...i.tags,...s.tags],i.paths={...i.paths,...s.paths},i.components=a(i.components,s.components)}}return i}catch(e){return{}}}(),d=(null==u?void 0:u.docsPath)||"api-docs";var l={id:d,validate:async function(e,s,n,t){if(null==u?void 0:u.paths){const o=await i(s,n);if(t)for(const e of t)o.paths[e]=u.paths[e];else o.paths=u.paths;u.components?o.components=u.components:(delete o.components.definitions,delete o.components.schemas),e.use(c.middleware({apiSpec:o})),e.use(((e,s,n,t)=>{n.status(e.status||500).json({message:e.message,errors:e.errors})}))}return e},handler:(e,{services:s,exceptions:n,logger:t,getSchema:o})=>{const{ServiceUnavailableException:c}=n,l={swaggerOptions:{url:`/${d}/oas`}};e.use("/",r.serve),e.get("/",r.setup({},l)),e.get("/oas",(async(e,n,r)=>{try{const e=await o(),r=await i(s,e),c=require(`${await p(".")}/package.json`);r.info.title=c.name,r.info.version=c.version,r.info.description=c.description;try{if(null==u?void 0:u.paths)for(const e in u.paths)r.paths[e]=u.paths[e];if(null==u?void 0:u.tags)for(const e of u.tags)r.tags.push(e);(null==u?void 0:u.components)&&(r.components=a(u.components,r.components))}catch(e){t.info("No custom definitions")}n.json(r)}catch(e){return r(new c(e.message||e[0].message))}}))}};module.exports=l;
+"use strict";const e=require("js-yaml"),s=require("path"),n=require("fs"),t=process.cwd();let o;async function i(e,s){if(o)return JSON.parse(o);const{SpecificationService:n}=e,t=new n({accountability:{admin:!0},schema:s});return o=JSON.stringify(await t.oas.generate()),JSON.parse(o)}function a(e,s){return Object.entries(s).reduce(((e,[s,n])=>(e[s]=n&&"object"==typeof n?a(e[s]=e[s]||(Array.isArray(n)?[]:{}),n):n,e)),e)}const r=require("swagger-ui-express"),c=require("express-openapi-validator"),{findWorkspaceDir:p}=require("@pnpm/find-workspace-dir"),u=function(){try{const o=s.join(t,"./extensions/endpoints/oasconfig.yaml"),i=e.load(n.readFileSync(o,{encoding:"utf-8"})),r=s.join(t,"./extensions/endpoints"),c=n.readdirSync(r,{withFileTypes:!0});for(const s of c){const t=`${r}/${s.name}/oas.yaml`;if(s.isDirectory()&&n.existsSync(t)){const s=e.load(n.readFileSync(t,{encoding:"utf-8"}));i.tags=[...i.tags,...s.tags],i.paths={...i.paths,...s.paths},i.components=a(i.components||{},s.components||{})}}return i}catch(e){return{}}}(),d=(null==u?void 0:u.docsPath)||"api-docs";var l={id:d,validate:async function(e,s,n,t){if(null==u?void 0:u.paths){const o=await i(s,n);if(t)for(const e of t)o.paths[e]=u.paths[e];else o.paths=u.paths;u.components?o.components=u.components:(delete o.components.definitions,delete o.components.schemas),e.use(c.middleware({apiSpec:o})),e.use(((e,s,n,t)=>{n.status(e.status||500).json({message:e.message,errors:e.errors})}))}return e},handler:(e,{services:s,exceptions:n,logger:t,getSchema:o})=>{const{ServiceUnavailableException:c}=n,l={swaggerOptions:{url:`/${d}/oas`}};e.use("/",r.serve),e.get("/",r.setup({},l)),e.get("/oas",(async(e,n,r)=>{try{const e=await o(),r=await i(s,e),c=require(`${await p(".")}/package.json`);r.info.title=c.name,r.info.version=c.version,r.info.description=c.description;try{if(null==u?void 0:u.paths)for(const e in u.paths)r.paths[e]=u.paths[e];if(null==u?void 0:u.tags)for(const e of u.tags)r.tags.push(e);(null==u?void 0:u.components)&&(r.components=a(u.components,r.components))}catch(e){t.info("No custom definitions")}n.json(r)}catch(e){return r(new c(e.message||e[0].message))}}))}};module.exports=l;

package/dist/types.d.ts

@@ -0,0 +1,22 @@
+export interface oasconfig {
+    docsPath?: string;
+    tags?: Array<object>;
+    paths?: {
+        [key: string]: object;
+    };
+    components?: {
+        [key: string]: object;
+    };
+}
+export interface oas {
+    info: any;
+    docsPath: string;
+    tags: Array<any>;
+    paths: {
+        [key: string]: any;
+    };
+    components: {
+        [key: string]: any;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACrB,KAAK,CAAC,EAAE;QACJ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;KACzB,CAAC;IACF,UAAU,CAAC,EAAE;QACT,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;KACzB,CAAC;CACL;AAED,MAAM,WAAW,GAAG;IAChB,IAAI,EAAE,GAAG,CAAC;IACV,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IACjB,KAAK,EAAE;QACH,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;KACtB,CAAC;IACF,UAAU,EAAE;QACR,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;KACtB,CAAC;CACL"}

package/dist/utils.d.ts

@@ -0,0 +1,6 @@
+import { SchemaOverview } from '@directus/shared/types';
+import { oas, oasconfig } from './types';
+export declare function getConfig(): oasconfig;
+export declare function getOas(services: any, schema: SchemaOverview): Promise<oas>;
+export declare function merge(a: any, b: any): any;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAUzC,wBAAgB,SAAS,IAAI,SAAS,CAqBrC;AAED,wBAAsB,MAAM,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,CAYhF;AAED,wBAAgB,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,OAKnC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "directus-extension-api-docs",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "description": "directus extension for swagger interface and custom endpoints definitions",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -40,14 +40,14 @@
   },
   "devDependencies": {
     "@babel/preset-env": "^7.20.2",
-    "@directus/extensions-sdk": "^9.20.4",
+    "@directus/extensions-sdk": "^9.21.0",
     "@types/express": "^4.17.14",
     "@types/jest": "^29.2.3",
     "@types/node": "^18.11.9",
     "@typescript-eslint/eslint-plugin": "^5.43.0",
     "@typescript-eslint/parser": "^5.43.0",
     "babel-jest": "^29.3.1",
-    "eslint": "^8.27.0",
+    "eslint": "^8.28.0",
     "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-import": "^2.26.0",
     "eslint-plugin-prettier": "^4.2.1",