directus-extension-api-docs v1.9.1
directus-extension-api-docs
Directus Extension to include a Swagger interface and custom endpoints definitions
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')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 tagspaths
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'
info:
title: my-directus-bo
version: 1.5.0
description: my server description
tags:
- name: MyCustomTag
description: MyCustomTag description
publishedTags:
- MyCustomTag
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 tagspaths
optional openapi custom pathscomponents
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 # 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) => {
...
});
},
};
3 days ago
3 days ago
2 months ago
3 months ago
3 months ago
3 months ago
3 months ago
4 months ago
6 months ago
7 months ago
7 months ago
9 months ago
10 months ago
12 months ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago