{"id":23031927,"url":"https://github.com/sacconazzo/directus-extension-api-docs","last_synced_at":"2025-04-09T12:04:06.019Z","repository":{"id":63036933,"uuid":"564688442","full_name":"sacconazzo/directus-extension-api-docs","owner":"sacconazzo","description":"directus extension for swagger interface and custom endpoints definitions and validations","archived":false,"fork":false,"pushed_at":"2025-03-03T08:32:34.000Z","size":1185,"stargazers_count":37,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-02T11:04:21.547Z","etag":null,"topics":["api-documentation","api-validator","custom-endpoints","directus","directus-extension","openapi","swagger","validation"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/directus-extension-api-docs","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sacconazzo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-11T09:07:30.000Z","updated_at":"2025-03-03T08:29:12.000Z","dependencies_parsed_at":"2023-01-31T10:01:22.006Z","dependency_job_id":"450a1ba2-7900-4a37-8163-525f6444b441","html_url":"https://github.com/sacconazzo/directus-extension-api-docs","commit_stats":{"total_commits":58,"total_committers":3,"mean_commits":"19.333333333333332","dds":0.4137931034482759,"last_synced_commit":"1a4eb69ddb95550015020552024a2af589b3f954"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sacconazzo%2Fdirectus-extension-api-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sacconazzo%2Fdirectus-extension-api-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sacconazzo%2Fdirectus-extension-api-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sacconazzo%2Fdirectus-extension-api-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sacconazzo","download_url":"https://codeload.github.com/sacconazzo/directus-extension-api-docs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248036064,"owners_count":21037092,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-documentation","api-validator","custom-endpoints","directus","directus-extension","openapi","swagger","validation"],"created_at":"2024-12-15T15:48:30.657Z","updated_at":"2025-04-09T12:04:05.996Z","avatar_url":"https://github.com/sacconazzo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# directus-extension-api-docs\n\n\u003e Compatible with latest Directus versions and packaged extensions.\n\nDirectus Extension to include:\n\n-   a Swagger interface\n-   configurable autogenerated openapi specifications file\n    -- including custom endpoints definitions\n-   validation middleware on your custom endpoints (based on your openapi specifications). See below for details\n\n![workspace](assets/swagger.png)\n\n## Prerequisites\n\nWorking in a Directus nodejs project\n\nRef: https://github.com/directus/directus\n\n## Installation\n\n    npm install directus-extension-api-docs\n\n-   Swagger interface: by default `http://localhost:8055/api-docs`\n-   Openapi documentation: by default `http://localhost:8055/api-docs/oas`\n\n## Configuration (optional)\n\nTo include you custom endpoints in your documentation.\n\nCreate a `oasconfig.yaml` file under `/extensions` folder.\n\nOptions:\n\n-   `docsPath` _optional_ path where the interface will be (default 'api-docs')\n-   `info` _optional_ openapi server info (default extract from package.json)\n-   `tags` _optional_ openapi custom tags (will be merged with all standard and all customs tags)\n-   `publishedTags` _optional_ if specified, will be published definitions only for specified tags\n-   `paths` _optional_ openapi custom paths (will be merged with all standard and all customs paths)\n-   `components` _optional_ openapi custom components (will be merged with all standard and all customs tags)\n\nExample below:\n\n```\ndocsPath: 'api-docs'\ninfo:\n  title: my-directus-bo\n  version: 1.5.0\n  description: my server description\ntags:\n- name: MyCustomTag\n  description: MyCustomTag description\npublishedTags:\n- MyCustomTag\ncomponents:\n  schemas:\n    UserId:\n      type: object\n      required:\n      - user_id\n      x-collection: directus_users\n      properties:\n        user_id:\n          description: Unique identifier for the user.\n          example: 63716273-0f29-4648-8a2a-2af2948f6f78\n          type: string\n\n```\n\n## Definitions (optional)\n\nFor each endpoint extension, you can define api's including a file `oas.yaml` in root path of your extension endpoint folder.\n\nProperties:\n\n-   `tags` _optional_ openapi custom tags\n-   `paths` _optional_ openapi custom paths\n-   `components` _optional_ openapi custom components\n\nExemple below (`./extensions/my-endpoint-extensions/oas.yaml`) :\n\n```\ntags:\n- name: MyCustomTag2\n  description: MyCustomTag description2\npaths:\n  \"/my-custom-path/my-endpoint\":\n    post:\n      security:\n        - Auth: [ ]\n      summary: Validate email\n      description: Validate email\n      tags:\n        - MyCustomTag2\n        - MyCustomTag\n      requestBody:\n        content:\n          application/json:\n            schema:\n              \"$ref\": \"#/components/schemas/UserId\"\n      responses:\n        '200':\n          description: Successful request\n          content:\n            application/json:\n              schema:\n                \"$ref\": \"#/components/schemas/Users\"\n        '401':\n          description: Unauthorized\n          content: {}\n        '422':\n          description: Unprocessable Entity\n          content: {}\n        '500':\n          description: Server Error\n          content: {}\ncomponents:\n  schemas:\n    Users:\n      type: object # ref to standard components declaring it empty\n  securitySchemes:\n    Auth:\n      in: header\n      name: Authorization\n      type: apiKey\n```\n\n### Legacy mode\n\nConfiguration and definitions can also be managed in this structure:\n\n```\n- ./extensions/\n  - endpoints/\n    - oasconfig.yaml\n    - my-endpoint-extensions/\n      - oas.yaml\n    - my-endpoint-extensions2/\n      - oas.yaml\n```\n\n## Validations (optional)\n\nYou can enable a request validations middleware based on your custom definitions.\n\nCall `validate` function inside your custom endpoint source (`./extensions/my-endpoint-extensions/src/index.js`).\n\nPass your `router`, `services`, `schema` and a list (_optional_) of endpoints you want to validate.\n\nExample below:\n\n```\nconst { validate } = require('directus-extension-api-docs')\n\nexport default {\n    id: 'my-custom-path',\n    handler: async (router, { services, getSchema }) =\u003e {\n        const schema = await getSchema();\n        await validate(router, services, schema); // Enable validator\n\n        router.post('/my-endpoint', async (req, res, next) =\u003e {\n            ...\n        })\n    },\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsacconazzo%2Fdirectus-extension-api-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsacconazzo%2Fdirectus-extension-api-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsacconazzo%2Fdirectus-extension-api-docs/lists"}