strapi-swagger-custom-paths

Easily generate OpenAPI paths for the Strapi documentation plugin by automatically reading all your custom route definitions (01-custom.js) from each API. Supports both TypeScript and JavaScript Strapi projects.

• NPM Package
• GitHub Repository

Features

• Reads all src/api/<content-type>/routes/01-custom.js files in your Strapi project.
• Returns a valid OpenAPI paths object for use in Strapi's documentation plugin.
• Works with both TypeScript and JavaScript projects.
• Minimal configuration: just add your custom route files and reference the utility in your documentation config.

Installation

Install with your favorite package manager:

# npm
npm install strapi-swagger-custom-paths

# yarn
yarn add strapi-swagger-custom-paths

# pnpm
pnpm add strapi-swagger-custom-paths

# bun
bun add strapi-swagger-custom-paths

More information about Strapi documentation

For more details about how Strapi's documentation plugin works, see the official docs: https://docs.strapi.io/cms/plugins/documentation

How it works

• The function getCustomSwaggerPaths() will scan your Strapi project's src/api folder for all routes/01-custom.js files.
• It will merge all Swagger/OpenAPI route definitions and return a single paths object ready to use in your documentation plugin config.

Where does the Swagger data come from?

This package automatically collects Swagger/OpenAPI documentation from each custom route file in your Strapi project.

• It looks for files named 01-custom.js or 01-custom.ts inside each API folder: src/api/<content-type>/routes/01-custom.js.
• Each route object should include a config.swagger property, which follows the OpenAPI specification for that HTTP method and path.
• All swagger objects are merged into the paths section of your final OpenAPI documentation.

You can include any valid OpenAPI fields (summary, description, parameters, requestBody, responses, etc.) inside config.swagger.

Example: Custom Route File

JavaScript (src/api/my-content-type/routes/01-custom.js)

module.exports = {
  routes: [
    {
      method: 'GET',
      path: '/my-content-type/current',
      handler: 'my-content-type.getCurrent',
      config: {
        tags: ['MyContentType'],
        swagger: {
          summary: 'Get current MyContentType',
          description: 'Retrieve the current MyContentType',
          operationId: 'getCurrent',
          tags: ['MyContentType'],
        },
      },
    },
  ],
};

TypeScript (src/api/my-content-type/routes/01-custom.ts)

export default {
  routes: [
    {
      method: 'GET',
      path: '/my-content-type/current',
      handler: 'my-content-type.getCurrent',
      config: {
        tags: ['MyContentType'],
        swagger: {
          summary: 'Get current MyContentType',
          description: 'Retrieve the current MyContentType',
          operationId: 'getCurrent',
          tags: ['MyContentType'],
        },
      },
    },
  ],
};

Usage in Strapi plugins config

TypeScript Example (config/plugins.ts)

import { getCustomSwaggerPaths } from 'strapi-swagger-custom-paths'; // Add this line

export default () => ({
  documentation: {
    enabled: true,
    config: {
      openapi: "3.0.0",
      info: {
        version: "1.0.0",
        title: "Documentation",
        description: "",
        termsOfService: "YOUR_TERMS_OF_SERVICE_URL",
        contact: {
          name: "Team",
          email: "[email protected]",
          url: "mywebsite.io"
        },
        license: {
          name: "Apache 2.0",
          url: "https://www.apache.org/licenses/LICENSE-2.0.html"
        }
      },
      "x-strapi-config": {
        plugins: ["upload", "users-permissions"],
        path: "/documentation"
      },
      servers: [
        {
          url: "http://localhost:1337/api",
          description: "Development server"
        }
      ],
      externalDocs: {
        description: "Find out more",
        url: "https://docs.strapi.io/developer-docs/latest/getting-started/introduction.html"
      },
      security: [
        {
          bearerAuth: []
        }
      ],
      paths: getCustomSwaggerPaths(), // Add this line
    }
  },
});

JavaScript Example (config/plugins.js)

const { getCustomSwaggerPaths } = require('strapi-swagger-custom-paths'); // Add this line

module.exports = () => ({
  documentation: {
    enabled: true,
    config: {
      openapi: "3.0.0",
      info: {
        version: "1.0.0",
        title: "Documentation",
        description: "",
        termsOfService: "YOUR_TERMS_OF_SERVICE_URL",
        contact: {
          name: "Team",
          email: "[email protected]",
          url: "mywebsite.io"
        },
        license: {
          name: "Apache 2.0",
          url: "https://www.apache.org/licenses/LICENSE-2.0.html"
        }
      },
      "x-strapi-config": {
        plugins: ["upload", "users-permissions"],
        path: "/documentation"
      },
      servers: [
        {
          url: "http://localhost:1337/api",
          description: "Development server"
        }
      ],
      externalDocs: {
        description: "Find out more",
        url: "https://docs.strapi.io/developer-docs/latest/getting-started/introduction.html"
      },
      security: [
        {
          bearerAuth: []
        }
      ],
      paths: getCustomSwaggerPaths(), // Add this line
    }
  },
});

Requirements

• Node.js: >= 16.x
• Strapi: v4.x or v5.x
• Works with both JavaScript and TypeScript Strapi projects.

Tested versions

• Node.js: 16.x, 18.x, 20.x
• Strapi: 4.15.0, 5.12.5

License

MIT

Contributing

Pull requests and issues are welcome! Please open an issue or PR on GitHub.

You can include any valid OpenAPI fields (summary, description, parameters, requestBody, responses, etc.) inside config.swagger.

Author

DanSP89 (https://github.com/dansp89)