directus-extension-api-docs 1.3.4 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +130 -125
  2. package/dist/index.js +1 -1
  3. package/package.json +4 -3
package/README.md CHANGED
@@ -1,125 +1,130 @@
1
- # directus-extension-api-docs
2
-
3
- Directus Extension to include a Swagger interface and custom endpoints definitions
4
-
5
- ![workspace](assets/swagger.png)
6
-
7
- All directus endpoints are autogenerated on runtime.
8
-
9
- **You can enable validations middleware based on your custom definitions. See below**
10
-
11
- ## Prerequisites
12
-
13
- Working in a Directus nodejs project
14
-
15
- Ref: https://github.com/directus/directus
16
-
17
- ## Installation
18
-
19
- npm install directus-extension-api-docs
20
-
21
- ## Configuration (optional)
22
-
23
- For include you custom endpoints.
24
-
25
- Create a `oasconfig.js` file under `/extensions/endpoints` folder.
26
-
27
- Options:
28
-
29
- - `docsPath` _optional_ path where the interface will be (default 'api-docs')
30
- - `tags` _optional_ openapi custom tags
31
- - `paths` _optional_ openapi custom paths
32
- - `components` _optional_ openapi custom components (you can ref to directus standard components declaring them empty)
33
-
34
- Example below:
35
-
36
- ```
37
- module.exports = {
38
- docsPath: 'api-docs'
39
- tags: [
40
- {
41
- name: 'MyCustomTag',
42
- description: 'MyCustomTag description',
43
- },
44
- ],
45
- paths: {
46
- '/my-custom-path/my-endpoint': {
47
- post: {
48
- summary: 'do something',
49
- description: 'do something',
50
- requestBody: {
51
- content: {
52
- 'application/json': {
53
- schema: {
54
- type: 'object',
55
- required: ['field'],
56
- properties: {
57
- field: {
58
- type: 'string',
59
- },
60
- },
61
- },
62
- },
63
- },
64
- responses: {
65
- '200': {
66
- description: 'Successful request',
67
- content: {
68
- 'application/json': {
69
- schema: {
70
- type: 'object',
71
- properties: {
72
- field: {
73
- type: 'string',
74
- },
75
- },
76
- },
77
- },
78
- },
79
- },
80
- '401': {
81
- description: 'Unauthorized',
82
- content: {},
83
- },
84
- '404': {
85
- description: 'Not Found',
86
- content: {},
87
- },
88
- },
89
- tags: ['MyCustomTag', 'Assets'],
90
- },
91
- },
92
- },
93
- },
94
- components: {},
95
- };
96
- ```
97
-
98
- ## Validations (optional)
99
-
100
- You can enable a request validations middleware based on your custom definitions.
101
-
102
- Call `validate` function inside your custom endpoint registration.
103
-
104
- Pass your `router`, `services`, `schema` and a list (_optional_) of endpoints you want to validate.
105
-
106
- Example below:
107
-
108
- ```
109
- const { validate } = require('directus-extension-api-docs');
110
-
111
- const id = 'my-custom-path';
112
-
113
- module.exports = {
114
- id,
115
- handler: async function registerEndpoint(router, { services, getSchema }) {
116
-
117
- const schema = await getSchema();
118
- await validate(router, services, schema); // Enable validator for custom endpoints
119
-
120
- router.post('/my-endpoint', async (req, res, next) => {
121
- ...
122
- });
123
- },
124
- };
125
- ```
1
+ # directus-extension-api-docs
2
+
3
+ Directus Extension to include a Swagger interface and custom endpoints definitions
4
+
5
+ ![workspace](assets/swagger.png)
6
+
7
+ All directus endpoints are autogenerated on runtime.
8
+
9
+ **You can enable validations middleware based on your custom definitions. See below**
10
+
11
+ ## Prerequisites
12
+
13
+ Working in a Directus nodejs project
14
+
15
+ Ref: https://github.com/directus/directus
16
+
17
+ ## Installation
18
+
19
+ npm install directus-extension-api-docs
20
+
21
+ ## Configuration (optional)
22
+
23
+ For include you custom endpoints.
24
+
25
+ Create a `oasconfig.yaml` file under `/extensions/endpoints` folder.
26
+
27
+ Options:
28
+
29
+ - `docsPath` _optional_ path where the interface will be (default 'api-docs')
30
+ - `tags` _optional_ openapi custom tags (will be merged with all standard and all customs tags)
31
+ - `paths` _optional_ openapi custom paths (will be merged with all standard and all customs paths)
32
+ - `components` _optional_ openapi custom components (will be merged with all standard and all customs tags)
33
+
34
+ Example below:
35
+
36
+ ```
37
+ docsPath: 'api-docs'
38
+ tags:
39
+ - name: MyCustomTag
40
+ description: MyCustomTag description
41
+ components:
42
+ schemas:
43
+ UserId:
44
+ type: object
45
+ required:
46
+ - user_id
47
+ x-collection: directus_users
48
+ properties:
49
+ user_id:
50
+ description: Unique identifier for the user.
51
+ example: 63716273-0f29-4648-8a2a-2af2948f6f78
52
+ type: string
53
+
54
+ ```
55
+
56
+ ## Definitions (optional)
57
+
58
+ For each custom endpoints group, you can define openapi including a file `oas.yaml` on root of your group folder.
59
+
60
+ Properties:
61
+
62
+ - `tags` _optional_ openapi custom tags
63
+ - `paths` _optional_ openapi custom paths
64
+ - `components` _optional_ openapi custom components
65
+
66
+ Exemple below (`./extensions/endpoints/my-custom-path/oas.yaml`) :
67
+
68
+ ```
69
+ tags:
70
+ - name: MyCustomTag2
71
+ description: MyCustomTag description2
72
+ paths:
73
+ "/my-custom-path/my-endpoint":
74
+ post:
75
+ summary: Validate email
76
+ description: Validate email
77
+ tags:
78
+ - MyCustomTag2
79
+ - MyCustomTag
80
+ requestBody:
81
+ content:
82
+ application/json:
83
+ schema:
84
+ "$ref": "#/components/schemas/Users"
85
+ responses:
86
+ '200':
87
+ description: Successful request
88
+ content:
89
+ application/json:
90
+ schema:
91
+ "$ref": "#/components/schemas/User" // you can ref to standard components
92
+ '401':
93
+ description: Unauthorized
94
+ content: {}
95
+ '422':
96
+ description: Unprocessable Entity
97
+ content: {}
98
+ '500':
99
+ description: Server Error
100
+ content: {}
101
+ ```
102
+
103
+ ## Validations (optional)
104
+
105
+ You can enable a request validations middleware based on your custom definitions.
106
+
107
+ Call `validate` function inside your custom endpoint registration.
108
+
109
+ Pass your `router`, `services`, `schema` and a list (_optional_) of endpoints you want to validate.
110
+
111
+ Example below:
112
+
113
+ ```
114
+ const { validate } = require('directus-extension-api-docs');
115
+
116
+ const id = 'my-custom-path';
117
+
118
+ module.exports = {
119
+ id,
120
+ handler: async function registerEndpoint(router, { services, getSchema }) {
121
+
122
+ const schema = await getSchema();
123
+ await validate(router, services, schema); // Enable validator for custom endpoints
124
+
125
+ router.post('/my-endpoint', async (req, res, next) => {
126
+ ...
127
+ });
128
+ },
129
+ };
130
+ ```
package/dist/index.js CHANGED
@@ -1 +1 @@
1
- "use strict";const e=require("swagger-ui-express"),s=require("express-openapi-validator"),{findWorkspaceDir:t}=require("@pnpm/find-workspace-dir"),n=require("path"),o=process.cwd();let i;const r=function(){try{return require(n.join(o,"./extensions/endpoints/oasconfig.js"))}catch(e){return{}}}();async function a(e,s){if(i)return JSON.parse(i);const{SpecificationService:t}=e,n=new t({accountability:{admin:!0},schema:s});return i=JSON.stringify(await n.oas.generate()),JSON.parse(i)}function c(e,s){return Object.entries(s).reduce(((e,[s,t])=>(e[s]=t&&"object"==typeof t?c(e[s]=e[s]||(Array.isArray(t)?[]:{}),t):t,e)),e)}const p=(null==r?void 0:r.docsPath)||"api-docs";var u={id:p,validate:async function(e,t,n,o){if(null==r?void 0:r.paths){const i=await a(t,n);if(o)for(const e of o)i.paths[e]=r.paths[e];else i.paths=r.paths;r.components?i.components=r.components:(delete i.components.definitions,delete i.components.schemas),e.use(s.middleware({apiSpec:i})),e.use(((e,s,t,n)=>{t.status(e.status||500).json({message:e.message,errors:e.errors})}))}return e},handler:(s,{services:n,exceptions:o,logger:i,getSchema:u})=>{const{ServiceUnavailableException:d}=o,f={swaggerOptions:{url:`/${p}/oas`}};s.use("/",e.serve),s.get("/",e.setup({},f)),s.get("/oas",(async(e,s,o)=>{try{const e=await u(),o=await a(n,e),p=require(`${await t(".")}/package.json`);o.info.title=p.name,o.info.version=p.version,o.info.description=p.description;try{if(null==r?void 0:r.paths)for(const e in r.paths)o.paths[e]=r.paths[e];if(null==r?void 0:r.tags)for(const e of r.tags)o.tags.push(e);(null==r?void 0:r.components)&&(o.components=c(r.components,o.components))}catch(e){i.info("No custom definitions")}s.json(o)}catch(e){return o(new d(e.message||e[0].message))}}))}};module.exports=u;
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.json"),i=e.load(n.readFileSync(o,{encoding:"utf-8"})),a=s.join(t,"./extensions/endpoints"),r=n.readdirSync(a,{withFileTypes:!0});for(const s of r){const t=`${a}/${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={...i.components,...s.components}}}return i}catch(e){return{}}}(),d=(null==u?void 0:u.docsPath)||"api-docs";var f={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,f={swaggerOptions:{url:`/${d}/oas`}};e.use("/",r.serve),e.get("/",r.setup({},f)),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=f;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "directus-extension-api-docs",
3
- "version": "1.3.4",
3
+ "version": "1.4.0",
4
4
  "description": "directus extension for swagger interface and custom endpoints definitions",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
@@ -35,13 +35,14 @@
35
35
  "dependencies": {
36
36
  "@pnpm/find-workspace-dir": "^5.0.0",
37
37
  "express-openapi-validator": "^4.13.8",
38
+ "js-yaml": "^4.1.0",
38
39
  "swagger-ui-express": "^4.6.0"
39
40
  },
40
41
  "devDependencies": {
41
42
  "@babel/preset-env": "^7.20.2",
42
43
  "@directus/extensions-sdk": "^9.20.4",
43
44
  "@types/express": "^4.17.14",
44
- "@types/jest": "^29.2.2",
45
+ "@types/jest": "^29.2.3",
45
46
  "@types/node": "^18.11.9",
46
47
  "@typescript-eslint/eslint-plugin": "^5.43.0",
47
48
  "@typescript-eslint/parser": "^5.43.0",
@@ -57,6 +58,6 @@
57
58
  "prettier": "^2.7.1",
58
59
  "ts-jest": "^29.0.3",
59
60
  "ts-node": "^10.9.1",
60
- "typescript": "^4.8.4"
61
+ "typescript": "^4.9.3"
61
62
  }
62
63
  }