refactor(openapi): upgrade to openapi 3.1

[hanspagel]

🔗 Linked issue

–

❓ Type of change

• 📖 Documentation (updates to the documentation, readme, or JSdoc annotations)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

1. The OpenAPI file we’re generating is set to be OpenAPI 3.0, which is fine. But we can safely make it 3.1, as this just has additions to the 3.0 specification. In other words: What works in 3.0, works in 3.1, too.

2. I’ve also removed the URL description from the OpenAPI file. Currently, the OpenAPI stuff is only rendered in local development, but we’d probably want to enable a production-use of it, too and the request URL is already dynamic.

3. The schemes property came from Swagger 2.0 and we can safely remove it here.

Looking forward to get your feedback!

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[pi0]

I’ve also removed the URL description from the OpenAPI file. Currently, the OpenAPI stuff is only rendered in local development, but we’d probably want to enable a production-use of it, too and the request URL is already dynamic.

sure but today, it is experimental and local only. what's the point of removing it?

[hanspagel]

Now that you’re asking, there’s probably no good reason. Sorry. :) I’ve added it again.