Not able to access endpoints for openapi.json and swagger.json

[ShubjeetPal]

Bug report

Not able to access endpoints for openapi.json and swagger.json

I am deploying Strapi v3.6.6 from my local (windows 2019 vm) to Azure App Service using Azure DevOps
I want to use the openapi spec endpoint to setup Strapi APIs in Azure API Management. These internal APIs will then be used by an Azure Static Web App frontend.
Before Setting up APIs in Azure API Management, I want to view the openapi.json and swagger.json through 'Public' role and then I will setup authentication for APIs
But I am not able to access endpoints for openapi.json and swagger.json from localhost.

I am only able to setup APIs in API manager by manually uploading the file full_documentation.json. I want to use the endpoint as it will always give the updated/ regenerated json whenever model is updated.

Steps to reproduce the behavior

As per documentation https://strapi.io/documentation/developer-docs/latest/development/plugins/documentation.html#swagger-json-and-openapi-json-files
the openapi.json and swagger.json should be accessible. But when I try the url on localhost
http://localhost:1337/documentation/v1.0.0/openapi.json
I get a 404-not found error.
I do not see any permissions to set under setting-> users and permissions plugins -> roles -> public.

Expected behavior

As per Strapi Documentation as given below it should be accessible.
If the default /documentation base URL is used, the endpoints exposed are:

• /documentation/swagger.json or /documentation/openapi.json: the OpenAPI spec for the latest version of your API. Both endpoints serve the same document.
• /documentation/vN.N.N/swagger.json or /documentation/vN.N.N/openapi.json: request the spec for a specific version of your API. For example: /documentation/v1.0.0/openapi.json

Screenshots

Code snippets

System

• Node.js version: 14.17.4
• NPM version: 6.14.14
• Strapi version: 3.6.6
• Database: postgres (PostgreSQL client for Node.js. pg 8.7.1)
• Operating system: Local on Azure vm (Windows 2019 server)
• strapi-plugin-documentation: 3.6.6

Additional context

Am I missing something?
Is this a bug?
Can you give an example how to access the endpoints for openapi.json and swagger.json.

[derrickmehaffy]

This is a templated message

Hello, please follow the issue template.

A proper issue submission let's us better understand the origin of your bug and therefore help you.

I will reopen your issue when we receive the issue following the template guidelines and properly fill out the template. You can see the template guidelines for bug reports here.

Please update the issue with the template and we can reopen this report.

Thank you.

[ShubjeetPal]

Hello, I have updated the issue following the template.
Please reopen this report

[hondem]

Please can we reopen this? Have the same issue now.

[ShubjeetPal]

Please can we reopen this? Have the same issue now.

Is this an existing issue?

[hondem]

Please can we reopen this? Have the same issue now.

Is this an existing issue?

Yes, it is.

[ShubjeetPal]

Please can we reopen this? Have the same issue now.

Is this an existing issue?

Yes, it is.

Is there any resolution or any workaround for it currently

[Kraudia]

I can confirm this issue. I have enabled all role permissions for documentation plugs but index permission just enables access to GET /documentation and /documentation/v:major(\d+).:minor(\d+).:patch(\d+).

Nothing happened, I am still getting 404 error during enetring http://localhost:1337/documentation/v1.0.0/openapi.json or http://localhost:1337/documentation/openapi.json.

I am afraid that the docs are outdated as I am not able to access those json files (openapi.json or swagger.json) because I really can't find any route that would serve them up.

I think workaround for it is implementation of own custom controller that returns /extensions/documentation/documentation/1.0.0/full_documentation.json file.

[MarkKragerup]

It currently seems that the only way to serve the json file as of right now, is through a custom controller. I can try to create a pull request for it later.

Here is how to go about it:
Create 2 folders in /api, called /swaggerjson/config and /swaggerjson/controllers.

In swaggerjson/config create a routes.json file and put the following code:

{ "routes": [ { "method": "GET", "path": "/swagger.json", "handler": "Swaggerjson.index" } ] }

In the /swaggerjson/controllers create a Swaggerjson.js file, and put the following code:

const fs = require("fs");
module.exports = {
  index: async ctx => fs.readFileSync('extensions/documentation/documentation/1.0.0/full_documentation.json', 'utf8')
};

You should now be able to access https://yourapi/swagger.json.

[Kraudia]

I have just created a similar workaround to @MarkKragerup solution but I implemented two endpoints as I wanted to use documentation's version as param.

• http://localhost:1337/docs/openapi.json
• http://localhost:1337/docs/v1.0.0/openapi.json

You would also need to send authorization header (use JWT token as Bearer) to access above endpoints.
Please create two new files:

app/api/docs/config/routes.json

{
  "routes": [
    {
      "method": "GET",
      "path": "/docs/openapi.json",
      "handler": "docs.index",
      "config": {
        "policies": [
          "plugins::documentation.index"
        ]
      }
    },
    {
      "method": "GET",
      "path": "/docs/v:major(\\d+).:minor(\\d+).:patch(\\d+)/openapi.json",
      "handler": "docs.index",
      "config": {
        "policies": [
          "plugins::documentation.index"
        ]
      }
    }
  ]
}

app/api/docs/controllers/docs.js

'use strict';

const fs = require('fs-extra');
const path = require('path');

module.exports = {
  index: async (ctx) => {
    try {
      const { major, minor, patch } = ctx.params;
      const version =
        major && minor && patch
          ? `${major}.${minor}.${patch}`
          : strapi.plugins.documentation.config.info.version;

      const openAPISpecsPath = path.join(
        strapi.config.appPath,
        'extensions',
        'documentation',
        'documentation',
        version,
        'full_documentation.json',
      );

      const documentation = fs.readFileSync(openAPISpecsPath, 'utf8');
      const response = JSON.parse(documentation);

      ctx.send(response);
    } catch (e) {
      strapi.log.error(e);
      ctx.badRequest(null, e.message);
    }
  },
};

It should work.

[MarkKragerup]

There is a pending PR on this issue - and a merged documentation PR. This explains why the documentation is incorrectly claiming it works - the base PR needs merging.

Base PR:
#8486

Doc PR:
strapi/documentation#351

[tommy92]

I'm using Strapi v4.1.12 and the documentation plugin in v4.2.2.

There is no way to access any of these:

• /documentation/v1.0.0/swagger.json
• /documentation/v1.0.0/openapi.json
• /documentation/swagger.json
• /documentation/openapi.json

Any ideas how to make it work?

[roelbeerens]

This is what I did:

Add src/extensions/documentation/controllers/documentation.js with the following content:

'use strict';
const fs = require('fs-extra');
const path = require('path');
module.exports = {
  async openapi(ctx) {
    try {
      const { major, minor, patch } = ctx.params;
      const version =
        major && minor && patch ? `${major}.${minor}.${patch}` : strapi.plugins.documentation.config('info.version');
      const openAPISpecsPath = path.join(
        strapi.dirs.app.src,
        'extensions',
        'documentation',
        'documentation',
        version,
        'full_documentation.json'
      );
      const documentation = fs.readFileSync(openAPISpecsPath, 'utf8');
      const response = JSON.parse(documentation);
      ctx.send(response);
    } catch (e) {
      strapi.log.error(e);
      ctx.badRequest(null, e.message);
    }
  }
};

Add src/extensions/documentation/routes/custom-documentation.js with the following content:

'use strict';
const restrictAccess = require('@strapi/plugin-documentation/server/middlewares/restrict-access');
/**
 * company router.
 */
module.exports = {
  routes: [
    {
      method: 'GET',
      path: '/openapi.json',
      handler: 'documentation.openapi',
      config: {
        auth: false,
        middlewares: [restrictAccess]
      }
    },
    {
      method: 'GET',
      path: '/v:major(\\d+).:minor(\\d+).:patch(\\d+)/openapi.json',
      handler: 'documentation.openapi',
      config: {
        auth: false,
        middlewares: [restrictAccess]
      }
    }
  ]
};

Add src/extensions/documentation/strapi-server.js with the following content:

'use strict';
const documentationController = require('./controllers/documentation');
const documentationRoutes = require('./routes/custom-documentation');
module.exports = async (plugin) => {
  // Controllers
  plugin.controllers.documentation = {
    ...plugin.controllers.documentation,
    ...documentationController
  };
  // Routes
  plugin.routes = [...plugin.routes, ...documentationRoutes.routes];
  return plugin;
};

Hopefully this helps somebody, would like to see these routes in the plugin though...

[grech-ca]

It's not directly related to the bug, but if you work on monorepo including both the app and the strapi, you can make a workaround like this

input: path.resolve(process.cwd(), '../admin/src/extensions/documentation/documentation/1.0.0/full_documentation.json'),

[xanghyr]

Thank you @roelbeerens !
This is perfectly working for me. It is sad to have to come find a solution in github issues, while it must be default behaviour...

Anyway, I have a problem, probably not related to your solution : my components do not have their "required" info.
For my fields in my collection types root, I can see which are required, but all my fields inside components I can't. Any idea of how to add this in the full_documentation.json ?

[AlexandrKurbanov19]

The problem has not been fixed in newer versions. The solution was the instruction roelbeerens. Thanks for your help!

[derrickmehaffy]

Hello,

In order to keep our GitHub issues clean and only related to bug reports I've moved your enhancement / feature requested over to our feedback database.

You can find your request here: https://feedback.strapi.io/developer-experience/p/not-able-to-access-endpoints-for-openapijson-and-swaggerjson

Thanks!

[robozb]

+1

[robozb]

If your frontend project is beside to your strapi files a good alternative to read the the file directly from the filesystem, for example:
npx openapi-typescript ../strapi/src/extensions/documentation/documentation/1.0.0/full_documentation.json -o src/lib/types/api-types.ts

[groteck]

In typescript this solution doesn't work because the package @strapi/plugin-documentation/server/middlewares/restrict-access is not exposed in the package.json and also there is no type definitions.