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: "contact-email@something.io",
          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: "contact-email@something.io",
          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)