directus-extension-api-docs

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

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 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'
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 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 # 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) => {
            ...
        });
    },
};