Use zod-openapi for API documentation

[scheidtdav]

Type of Change

• Dependency upgrade
• Bug fix (non-breaking change)
• Breaking change
  • e.g. a fixed bug or new feature that may break something else
• New feature
• Code quality improvements
  • e.g. refactoring, documentation, tests, tooling, ...

Implementation

As a POC I have replaced the documentation for the sign-in route with one generated via zod-openapi and corresponding zod schemas (that could potentially be shared between routes).
The docs page also got a little bit of an overhaul to make it easier to differentiate between regular API docs and integrations docs.

The zod schema makes the code of the actual api handler a lot more simple (there is almost no logic anymore). All of the "complexity" is within the schema definition which does generate its entire documentation as a side product. This nicely keeps the documentation aligned with the actual implementation and not only with whats supposedly implemented (a problem we have with the old docs and one that I came across while implementing this too!).

The build step is now also gone. What looks like a runtime generation is a little smarter though: Vites import.meta.glob is actually derived via statical analysis and thus should be very fast.

Totally open for opinions. Should I continue this?

Sidenote: Since there is nothing generated about the integrations spec, we might want to place it somewhere else or even convert it to an actual .yml file once and just put it under public assets?
There must be a better way than this right now... 🤔

Checklist

• I gave this pull request a meaningful title
• My pull request is targeting the dev branch
• [] I have added documentation to my code <-- README needs an update
• I have deleted code that I have commented out

Additional Information

• This PR closes swagger-jsdoc should be replaced #728

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	jsdom@​29.0.2

View full report