[Bug]: Documentation for custom routes [documentation plugin]

[khako]

Link to the documentation page or resource

https://market.strapi.io/plugins/@strapi-plugin-documentation

Describe the bug

The documentation plugin for strapi 4 dosen't create documentation for custom routes (or I didn't find info about it ?). For example I have the following routes:

- api
    - devices
        - routes
            - devices.js // core routes
            - custom.js // extended routes

The swagger documentation will only be generated for core routes and not for the extended routes.

Am I missing something ?

Additional context

Strapi v4

Suggested improvements or fixes

No response

Related issue(s)/PR(s)

No response

[stb13579]

Hello @khako, I am a Technical Writer at Strapi. I know that one of our developer squads is currently working to improve the Documentation plugin. I am going to share this issue with the team and try to find a solution. Thanks for opening an issue, it really helps us improve the documentation.

[stb13579]

@khako I see you linked to the plugin market. We also have documentation here that might be helpful. I will try to find time to test this myself during the week.

[I99Developer]

similar issue here: strapi 4.1.11 file structure: .api/messagewrapper/controllers/messagewrapper.js .api/messagewrapper/routes/messagewrapper.js .api/messagewrapper/models/schema.json

the documentation folder and file: .api/messagewrapper/documentation/1.0.0/messagewrapper does seem to get created but the messagewrapper.json file is empty: {}

I've followed instructions @StrapiShaun posted as well: created the settings.json file here: .extensions/documentation/config/

Interesting note: It's clear the settings file is used to some level, if I modify and add multiple servers to the servers object, they appear in the generated swagger doc, however plugin documentation is not being generated and also, if I modify the version in the info section it is also ignored.

I've attempted to delete npm modules and yarn.lock, reinstall and rebuild etc.. to no avail.

Hope this helps:

settings file:

{ "openapi": "3.0.0", "info": { "version": "2.0.0", "title": "DOCUMENTATION", "description": "", "termsOfService": "test.com", "contact": { "name": "TEAM", "email": "noone@test.com", "url": "test.com" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" } }, "x-strapi-config": { "path": "/documentation", "showGeneratedFiles": true, "generateDefaultResponse": true, "pluginsForWhichToGenerateDoc": [ "email", "upload", "users-permissions", "email-designer" ] }, "servers": [ { "url": "http://localhost:1337", "description": "Development server" } ], "externalDocs": { "description": "Find out more", "url": "https://strapi.io/documentation/" }, "security": [ { "bearerAuth": [] } ], "paths": {}, "tags": [], "components": {} }

[stb13579]

@I99Developer I am sorry you are having trouble with the plugin. I know our developers are working to improve the Documentation plugin in the near future. In the meantime, I will see what I can do to track down a solution for this problem.

[longpnmd]

similar issue

[longpnmd]

@khako this code working with me :)) ** note : this is not an orthodox workaround

merge routes

'use strict';

const { createCoreRouter } = require('@strapi/strapi').factories;

module.exports = (() => {
    const routerCore = createCoreRouter('api::devices.devices')
    return {
        get prefix() {
            return routerCore.prefix;
        },
        get routes() {
            return [
                ...routerCore.routes,
                ...require("./custom").routes,
            ]
        }
    }
})()

[mjcadz]

this is still an issue, plugin version 4.3.6

[stb13579]

this is still an issue, plugin version 4.3.6

Hi @mjcadz. The devs are working on a significant update for this plugin. I think the hope is to have it completed later this month or early in October. We have communicated the issues here so that they can be addressed.

[teuchezh]

same issue

[chc201627]

Hello, I have the same issue

[HOTeddy]

same issue

[Chessman97]

same issue

[DimitriGilbert]

Anything new on this front ?

[ShahidAbbas888]

I m facing same issue let me know if anyone has solution please.

[mayospacken]

I got the same issue.Is there any solution in a pipeline ?

[prawee]

+1 me too. on 4.10.6 version

[woodyjon]

Hello.

I have the same issue. This is the description of my issue, to make it clear:

I am creating a custom route, not based on a content type. See the printscreen:

the content of the healthcheck/routes/healthcheck.ts file is the following:

export default {
  routes: [
    {
      method: "GET",
      path: "/healthcheck",
      handler: "healthcheck.check_health",
      config: {
        find: {
          auth: false,
        },
      },
    },
  ],
};

But the documentation json file healthcheck/documentation/1.0.0/healthcheck.jsonis always set to

{}

and does not include the proper info.

[koliapp2019]

So we take it that with this bug, any custom API wouldn't have its documentation generated? Thanks for any insight into it.

[prawee]

@khako this code working with me :)) ** note : this is not an orthodox workaround

merge routes

'use strict';

const { createCoreRouter } = require('@strapi/strapi').factories;

module.exports = (() => {
    const routerCore = createCoreRouter('api::devices.devices')
    return {
        get prefix() {
            return routerCore.prefix;
        },
        get routes() {
            return [
                ...routerCore.routes,
                ...require("./custom").routes,
            ]
        }
    }
})()

thank you. save my day!

[nuqz]

@khako this code working with me :)) ** note : this is not an orthodox workaround

merge routes

'use strict';

const { createCoreRouter } = require('@strapi/strapi').factories;

module.exports = (() => {
    const routerCore = createCoreRouter('api::devices.devices')
    return {
        get prefix() {
            return routerCore.prefix;
        },
        get routes() {
            return [
                ...routerCore.routes,
                ...require("./custom").routes,
            ]
        }
    }
})()

Hello, everyone! Does anyone have ideas on how to convert this code to TypeScript?

UPD. Here is working example, but I'm in doubt if it typed well:

import { factories } from '@strapi/strapi';
import { Router } from '@strapi/strapi/lib/types/core-api/router';

import populated from './populated';

const coreRouter = factories.createCoreRouter('api::post.post') as unknown as Router
const customRouter = {
  get prefix() {
    return coreRouter.prefix
  },
  get routes() {
    return [
      ...coreRouter.routes,
      ...populated.routes,
    ]
  }
}

export default customRouter;

[Demacri]

I struggled with this issue a couple of days ago... digging deeper i was able to add a fix for it. https://github.com/strapi/strapi/pull/18142

While it's in review feel free to use the forked one by installing it with:

npm uninstall @strapi/plugin-documentation
npm install 'https://gitpkg.now.sh/Demacri/strapi/packages/plugins/documentation?main'

[pwizla]

Hi. I'm sorry you were all having issues with the Documentation plugin. I'll close this PR now because transferring maintenance of the Documentation plugin to the community is currently in discussion, and it's likely docs.strapi.io won't feature documentation for the plugin anymore with Strapi v5 docs.

[strapi-bot]

This issue has been mentioned on Strapi Community Forum. There might be relevant details there:

https://forum.strapi.io/t/solution-add-custom-routes-in-swagger-and-change-swagger-settings-based-on-swagger-with-strapi-4-default-overwrite/34408/2