Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sacconazzo/directus-extension-api-docs
directus extension for swagger interface and custom endpoints definitions and validations
https://github.com/sacconazzo/directus-extension-api-docs
api-documentation api-validator custom-endpoints directus directus-extension openapi swagger validation
Last synced: 2 days ago
JSON representation
directus extension for swagger interface and custom endpoints definitions and validations
- Host: GitHub
- URL: https://github.com/sacconazzo/directus-extension-api-docs
- Owner: sacconazzo
- License: mit
- Created: 2022-11-11T09:07:30.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-11-12T12:32:49.000Z (about 2 months ago)
- Last Synced: 2024-12-15T15:49:11.896Z (13 days ago)
- Topics: api-documentation, api-validator, custom-endpoints, directus, directus-extension, openapi, swagger, validation
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/directus-extension-api-docs
- Size: 1.65 MB
- Stars: 32
- Watchers: 2
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: license
Awesome Lists containing this project
README
# directus-extension-api-docs
> Compatible with latest Directus versions and packaged extensions.
Directus Extension to include:
- a Swagger interface
- configurable autogenerated openapi specifications file
-- including custom endpoints definitions
- validation middleware on your custom endpoints (based on your openapi specifications). See below for details
## Prerequisites
Working in a Directus nodejs project
Ref: https://github.com/directus/directus
## Installation
npm install directus-extension-api-docs
- Swagger interface: by default `http://localhost:8055/api-docs`
- Openapi documentation: by default `http://localhost:8055/api-docs/oas`
## Configuration (optional)
To include you custom endpoints in your documentation.
Create a `oasconfig.yaml` file under `/extensions` 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 endpoint extension, you can define api's including a file `oas.yaml` in root path of your extension endpoint folder.
Properties:
- `tags` _optional_ openapi custom tags
- `paths` _optional_ openapi custom paths
- `components` _optional_ openapi custom components
Exemple below (`./extensions/my-endpoint-extensions/oas.yaml`) :
```
tags:
- name: MyCustomTag2
description: MyCustomTag description2
paths:
"/my-custom-path/my-endpoint":
post:
security:
- Auth: [ ]
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
securitySchemes:
Auth:
in: header
name: Authorization
type: apiKey
```
### Legacy mode
Configuration and definitions can also be managed in this structure:
```
- ./extensions/
- endpoints/
- oasconfig.yaml
- my-endpoint-extensions/
- oas.yaml
- my-endpoint-extensions2/
- oas.yaml
```
## Validations (optional)
You can enable a request validations middleware based on your custom definitions.
Call `validate` function inside your custom endpoint source (`./extensions/my-endpoint-extensions/src/index.js`).
Pass your `router`, `services`, `schema` and a list (_optional_) of endpoints you want to validate.
Example below:
```
const { validate } = require('directus-extension-api-docs')
export default {
id: 'my-custom-path',
handler: async (router, { services, getSchema }) => {
const schema = await getSchema();
await validate(router, services, schema); // Enable validator
router.post('/my-endpoint', async (req, res, next) => {
...
})
},
}
```