search

strapi / documentation

Strapi Documentation
https://docs.strapi.io
Other
1.01k stars 1.07k forks source link

Swagger and openapi json files do not exists #2143

Open Justin-van-der-Velden opened 2 months ago

Justin-van-der-Velden commented 2 months ago

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 commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

I have the same issue and I'm using strapi@4.25.4.

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

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 commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

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

I'm available if you have any other questions.

faessler commented 1 month ago

@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 commented 1 month ago

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 👀