directus-extension-api-docs 1.4.2 → 1.4.4
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.
- package/README.md +134 -134
- package/package.json +63 -63
package/README.md
CHANGED
|
@@ -1,134 +1,134 @@
|
|
|
1
|
-
# directus-extension-api-docs
|
|
2
|
-
|
|
3
|
-
Directus Extension to include a Swagger interface and custom endpoints definitions
|
|
4
|
-
|
|
5
|
-
|
|
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 api's including a file `oas.yaml` in root path 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/UserId"
|
|
85
|
-
responses:
|
|
86
|
-
'200':
|
|
87
|
-
description: Successful request
|
|
88
|
-
content:
|
|
89
|
-
application/json:
|
|
90
|
-
schema:
|
|
91
|
-
"$ref": "#/components/schemas/Users"
|
|
92
|
-
'401':
|
|
93
|
-
description: Unauthorized
|
|
94
|
-
content: {}
|
|
95
|
-
'422':
|
|
96
|
-
description: Unprocessable Entity
|
|
97
|
-
content: {}
|
|
98
|
-
'500':
|
|
99
|
-
description: Server Error
|
|
100
|
-
content: {}
|
|
101
|
-
components:
|
|
102
|
-
schemas:
|
|
103
|
-
Users:
|
|
104
|
-
type: object # ref to standard components declaring it empty
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
## Validations (optional)
|
|
108
|
-
|
|
109
|
-
You can enable a request validations middleware based on your custom definitions.
|
|
110
|
-
|
|
111
|
-
Call `validate` function inside your custom endpoint registration.
|
|
112
|
-
|
|
113
|
-
Pass your `router`, `services`, `schema` and a list (_optional_) of endpoints you want to validate.
|
|
114
|
-
|
|
115
|
-
Example below:
|
|
116
|
-
|
|
117
|
-
```
|
|
118
|
-
const { validate } = require('directus-extension-api-docs');
|
|
119
|
-
|
|
120
|
-
const id = 'my-custom-path';
|
|
121
|
-
|
|
122
|
-
module.exports = {
|
|
123
|
-
id,
|
|
124
|
-
handler: async function registerEndpoint(router, { services, getSchema }) {
|
|
125
|
-
|
|
126
|
-
const schema = await getSchema();
|
|
127
|
-
await validate(router, services, schema); // Enable validator
|
|
128
|
-
|
|
129
|
-
router.post('/my-endpoint', async (req, res, next) => {
|
|
130
|
-
...
|
|
131
|
-
});
|
|
132
|
-
},
|
|
133
|
-
};
|
|
134
|
-
```
|
|
1
|
+
# directus-extension-api-docs
|
|
2
|
+
|
|
3
|
+
Directus Extension to include a Swagger interface and custom endpoints definitions
|
|
4
|
+
|
|
5
|
+
|
|
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 api's including a file `oas.yaml` in root path 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/UserId"
|
|
85
|
+
responses:
|
|
86
|
+
'200':
|
|
87
|
+
description: Successful request
|
|
88
|
+
content:
|
|
89
|
+
application/json:
|
|
90
|
+
schema:
|
|
91
|
+
"$ref": "#/components/schemas/Users"
|
|
92
|
+
'401':
|
|
93
|
+
description: Unauthorized
|
|
94
|
+
content: {}
|
|
95
|
+
'422':
|
|
96
|
+
description: Unprocessable Entity
|
|
97
|
+
content: {}
|
|
98
|
+
'500':
|
|
99
|
+
description: Server Error
|
|
100
|
+
content: {}
|
|
101
|
+
components:
|
|
102
|
+
schemas:
|
|
103
|
+
Users:
|
|
104
|
+
type: object # ref to standard components declaring it empty
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## Validations (optional)
|
|
108
|
+
|
|
109
|
+
You can enable a request validations middleware based on your custom definitions.
|
|
110
|
+
|
|
111
|
+
Call `validate` function inside your custom endpoint registration.
|
|
112
|
+
|
|
113
|
+
Pass your `router`, `services`, `schema` and a list (_optional_) of endpoints you want to validate.
|
|
114
|
+
|
|
115
|
+
Example below:
|
|
116
|
+
|
|
117
|
+
```
|
|
118
|
+
const { validate } = require('directus-extension-api-docs');
|
|
119
|
+
|
|
120
|
+
const id = 'my-custom-path';
|
|
121
|
+
|
|
122
|
+
module.exports = {
|
|
123
|
+
id,
|
|
124
|
+
handler: async function registerEndpoint(router, { services, getSchema }) {
|
|
125
|
+
|
|
126
|
+
const schema = await getSchema();
|
|
127
|
+
await validate(router, services, schema); // Enable validator
|
|
128
|
+
|
|
129
|
+
router.post('/my-endpoint', async (req, res, next) => {
|
|
130
|
+
...
|
|
131
|
+
});
|
|
132
|
+
},
|
|
133
|
+
};
|
|
134
|
+
```
|
package/package.json
CHANGED
|
@@ -1,63 +1,63 @@
|
|
|
1
|
-
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "directus-extension-api-docs",
|
|
3
|
+
"version": "1.4.4",
|
|
4
|
+
"description": "directus extension for swagger interface and custom endpoints definitions",
|
|
5
|
+
"main": "dist/index.js",
|
|
6
|
+
"types": "dist/index.d.ts",
|
|
7
|
+
"files": [
|
|
8
|
+
"dist",
|
|
9
|
+
"!*.map"
|
|
10
|
+
],
|
|
11
|
+
"repository": "https://github.com/sacconazzo/directus-extension-api-docs",
|
|
12
|
+
"homepage": "https://github.com/sacconazzo/directus-extension-api-docs#readme",
|
|
13
|
+
"keywords": [
|
|
14
|
+
"directus",
|
|
15
|
+
"directus-extension",
|
|
16
|
+
"directus-custom-endpoint",
|
|
17
|
+
"swagger",
|
|
18
|
+
"custom endpoints",
|
|
19
|
+
"openapi definition",
|
|
20
|
+
"openapi"
|
|
21
|
+
],
|
|
22
|
+
"directus:extension": {
|
|
23
|
+
"type": "endpoint",
|
|
24
|
+
"path": "dist/index.js",
|
|
25
|
+
"source": "src/index.ts",
|
|
26
|
+
"host": "^9.19.2"
|
|
27
|
+
},
|
|
28
|
+
"scripts": {
|
|
29
|
+
"test": "jest --verbose=true",
|
|
30
|
+
"lint": "eslint --ignore-path .gitignore --ext .ts tests/ src/",
|
|
31
|
+
"lint:fix": "pnpm lint --fix",
|
|
32
|
+
"build": "directus-extension build",
|
|
33
|
+
"dev": "directus-extension build -w --no-minify"
|
|
34
|
+
},
|
|
35
|
+
"dependencies": {
|
|
36
|
+
"@pnpm/find-workspace-dir": "^5.0.0",
|
|
37
|
+
"express-openapi-validator": "^4.13.8",
|
|
38
|
+
"js-yaml": "^4.1.0",
|
|
39
|
+
"swagger-ui-express": "^4.6.0"
|
|
40
|
+
},
|
|
41
|
+
"devDependencies": {
|
|
42
|
+
"@babel/preset-env": "^7.20.2",
|
|
43
|
+
"@directus/extensions-sdk": "^9.21.2",
|
|
44
|
+
"@types/express": "^4.17.15",
|
|
45
|
+
"@types/jest": "^29.2.4",
|
|
46
|
+
"@types/node": "^18.11.16",
|
|
47
|
+
"@typescript-eslint/eslint-plugin": "^5.46.1",
|
|
48
|
+
"@typescript-eslint/parser": "^5.46.1",
|
|
49
|
+
"babel-jest": "^29.3.1",
|
|
50
|
+
"eslint": "^8.30.0",
|
|
51
|
+
"eslint-config-prettier": "^8.5.0",
|
|
52
|
+
"eslint-plugin-import": "^2.26.0",
|
|
53
|
+
"eslint-plugin-prettier": "^4.2.1",
|
|
54
|
+
"express": "^4.18.2",
|
|
55
|
+
"jest": "^29.3.1",
|
|
56
|
+
"jest-extended": "^3.2.0",
|
|
57
|
+
"openapi-schema-validator": "^12.1.0",
|
|
58
|
+
"prettier": "^2.8.1",
|
|
59
|
+
"ts-jest": "^29.0.3",
|
|
60
|
+
"ts-node": "^10.9.1",
|
|
61
|
+
"typescript": "^4.9.4"
|
|
62
|
+
}
|
|
63
|
+
}
|