Swagger and openapi json files do not exists

[Justin-van-der-Velden]

Link to the documentation page or resource

https://docs-v3.strapi.io/developer-docs/latest/development/plugins/documentation.html#overriding-the-suggested-documentation

Describe the bug

Hello,

The documentation of the plugin tells me that the plugin creates a swagger.json and an openapi.json file. I just have the default settings and not tweaked with url's. Somehow these files are not reachable. I get a 404 when I try to go to:

http://localhost:1337/documentation/v1.0.0/swagger.json

Strapi version: 4.25.3 Strapi documentation plugin version: 4.25.2

Is there some tweaking needed to acces those files?

Additional context

No response

Suggested improvements or fixes

No response

Related issue(s)/PR(s)

No response

[pwizla]

Hi @Justin-van-der-Velden, I've asked Strapi core engineers about it, I will get back to you as soon as I know more.

[pwizla]

Hi again @Justin-van-der-Velden. Strapi recently released v4.25.4. While there is no fix for Swagger/the Documentation plugin listed in the release notes, could you please give it another try?

If the issue persists I will follow-up with Strapi engineers.

[pwizla]

Oh, sorry, I've just noticed something 💡 The link you included is for Strapi v3. Is your project running on Strapi v3 or on Strapi v4? 🤔 v3 is now end-of-life, unsupported. Here's the corresponding documentation for Strapi 4: https://docs.strapi.io/dev-docs/plugins/documentation#overriding-the-generated-documentation

[faessler]

I have the same issue and I'm using [email protected].

Seems like openapi.json was never available and it was requested a couple of times in the past:

• https://github.com/strapi/documentation/issues/590
• https://github.com/strapi/strapi/issues/10734
• https://github.com/strapi/documentation/issues/366

I believe it would be a nice feature to add because it will allow type generation like this openapi-typescript https://foo.bar/documentation/1.0.0/openapi.json -o ./schema.d.ts in an external frontend project.

[pwizla]

Thanks for the additional information, @faessler. Everytime I asked Strapi engineers about full Open API compliance in the past, the answer was that Strapi's Content API can't be made fully Open API compliant due to its complex/custom nature, and it will become even more complex in Strapi 5. The only solution would be that the Strapi team builds its own custom Open API spec, but it's not on our roadmap.

I'll follow-up with engineers on this issue but I think the Documentation plugin is currently deprioritized while they're hard at work polishing the upcoming Strapi 5.

[faessler]

Hey @pwizla 🙋🏼‍♂️ Thanks for your quick reply. I've opened a PR with the changes needed to have the /openapi.json route available. (my first PR here, I tried my best to follow the contribution guidelines)

Not sure how we go from here? I guess we also need to update the Strapi documentation of the documentation plugin?

[pwizla]

Thank you very much, @faessler! Much appreciated 🤗 Indeed, if you feel like updating the documentation as well, could you please:

• [ ] create the documentation PR following our contribution guide
• [ ] ensure both the strapi/strapi and strapi/documentation PRs mention each other in the "Related issues/PRs" section of the PRs description

I'm available if you have any other questions.

[faessler]

@pwizla the PR with documentation update for the documentation plugin is created https://github.com/strapi/documentation/pull/2159. I hope it's okay like that. 🤞

Let me know if there is anything else otherwise I'm gonna leave this with you now. 🙂

[pwizla]

Perfect, @faessler, thank you! Your docs PR is approved. I'll wait for engineers to merge the corresponding strapi/strapi PR before merging the docs PR 👀

[razzeee]

Just stumbled over this and it would be great if this was fixed.

I guess I can try to copy the json by hand out of the swagger-ui page, but that's a huge pain.

[pwizla]

Hi there. The corresponding strapi/strapi (20871) is still under review. Engineers are busy polishing Strapi 5.x.x. So unfortunately I can't merge this docs PR until the related strapi/strapi PR is merged.

[gevera]

Thats a bummer. Looking forward to get access to openapi.json file with all the schemas

[razzeee]

Hi there. The corresponding strapi/strapi (20871) is still under review. Engineers are busy polishing Strapi 5.x.x. So unfortunately I can't merge this docs PR until the related strapi/strapi PR is merged.

Wondering, if this would be available for 4.x.x then? Can it be backported?

[faessler]

It was merged into the v4 branch. I guess it will be included with the next v4 feature release.

@Marc-Roig, @pwizla can it also be added for v5?

[pwizla]

Hi @faessler,

I'm not sure the strapi/strapi #20871 PR will also be ported to Strapi 5. @Marc-Roig, any idea? If yes, I can also port the related docs PR (#2159) to Strapi 5.

[faessler]

Hi @pwizla & @Marc-Roig, it's been some time and I wanted to ask if we could port this to v5? Then we can finally close this issue 🙂🤞

[pwizla]

Hi @faessler. I'm convinced our users would be happy if this is ported to v5. I could handle the documentation part if you want. However I'll be off for end-of-year holidays in a few hours. I could get back to this with pleasure in January. Please feel free to ping me again by this time. cc (@Marc-Roig)

[faessler]

Hello @Marc-Roig & @pwizla, hope you had a great start into 2025! 🥳

I wanted to ping you again to check if we can port the feature to v5? 🤞

[pwizla]

Thanks for the ping, @faessler, and hope you had a great start into 2025 too! I can't decide for the code implementation part in strapi/strapi as I'm in charge of docs content only (that is, the website; the "Documentation" plugin, despite its name, is not maintained by the Strapi Documentation team who does not include any full-time engineer—the plugin is maintained by the Strapi core engineers). Pinging @Marc-Roig who is an engineer and could let you know about porting the feature to v5.

[gevera]

As a temporary workaround, I have created a custom route where I serve the generated json from the plugin.

[dominikfryc]

@pwizla @Marc-Roig Any update? It's quite a critical feature

[pwizla]

I'm sorry @dominikfryc, I've just ping'ed engineers again on this topic, and the answer is that the plugin is not actively maintained at the moment.

There's is another OpenAPI-related initiative at Strapi whose result will be publicly shared soon.

Also, just so you know:

• I'm the Lead Technical Writer at Strapi, but not a strapi/strapi maintainer. I maintain strapi/documentation.
• The present repo, strapi/documentation, is for the documentation website content, hosted at docs.strapi.io, and nothing else.
• The "Documentation" plugin, despite its name, is not maintained by the Documentation team. It's just a plugin like the other official Strapi plugins that the Strapi core engineers can maintain.

I will now lock the discussion.

👉 If anyone has issues with the plugin, please feel free to:

• report them on the strapi/strapi monorepo issues
• ask for updates of its README file, which is also managed by Strapi core engineers
• add feedback to feedback.strapi.io, under the "Feature Requests" or "Developer Experience" categories