Directus Extension to include
- a Swagger interface
- custom endpoints definitions
- custom endpoints data validation based on your definitions
All directus endpoints are autogenerated on runtime.
You can enable validations middleware based on your custom definitions. See below
Working in a Directus nodejs project
Ref: https://github.com/directus/directus
npm install directus-extension-api-docs
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
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
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) => {
...
});
},
};