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

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	70.25%	2128 / 3029
🔵	Statements	68.76%	2197 / 3195
🔵	Functions	68.01%	419 / 616
🔵	Branches	53.94%	1013 / 1878

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
app/utils.ts	10%	7.59%	7.4%	8.1%	41-49, 66-265
app/lib/device-transform.ts	100%	100%	100%	100%
app/lib/jwt.ts	88.52%	66.66%	100%	91.22%	67, 69, 83, 132, 148, 181-182, 188-189, 227, 261, 289, 291, 296
app/lib/request-parsing.ts	85.07%	59.64%	100%	85.07%	36, 116-122, 131, 149, 196, 206-211, 236-240
app/lib/responses.ts	93.75%	100%	87.5%	93.33%	84, 108
app/lib/user-transform.ts	100%	50%	100%	100%
app/lib/api-schemas/devices.ts	62.5%	50%	68.42%	61.11%	80-81, 91, 100-103, 114-131, 139, 159-164
app/lib/api-schemas/query.ts	100%	100%	100%	100%
app/lib/openapi/messages.ts	100%	100%	100%	100%
app/lib/openapi/errors/index.ts	100%	100%	100%	100%
app/lib/openapi/errors/responses.ts	96.55%	91.66%	92.85%	96.42%	68
app/lib/openapi/errors/schemas.ts	100%	100%	100%	100%
app/lib/openapi/schemas/auth.ts	100%	100%	100%	100%
app/lib/openapi/schemas/claim.ts	100%	100%	100%	100%
app/lib/openapi/schemas/common.ts	100%	100%	100%	100%
app/lib/openapi/schemas/device.ts	100%	83.33%	100%	100%
app/lib/openapi/schemas/location.ts	100%	100%	100%	100%
app/lib/openapi/schemas/measurement.ts	100%	100%	100%	100%
app/lib/openapi/schemas/user.ts	100%	100%	100%	100%
app/middleware/content-type-header.server.ts	51.16%	28%	53.84%	55.26%	5, 18, 35-48, 55-69, 78, 86, 94, 103-109
app/routes/api.boxes.$deviceId.$sensorId.measurements.ts	83.72%	70%	100%	82.5%	137-139, 147, 155, 171-173, 179, 208, 213-215
app/routes/api.boxes.$deviceId.$sensorId.ts	75%	46.87%	100%	75%	154-156, 164, 170-172, 184, 192, 198, 219, 234, 245-253
app/routes/api.boxes.$deviceId.data.$sensorId.ts	73.23%	50.9%	100%	81.96%	180, 197, 200, 223, 232-234, 242-248, 270, 273, 278, 284-293, 302, 305, 308, 312, 315
app/routes/api.boxes.$deviceId.data.ts	92.3%	60.71%	100%	92.3%	241, 263, 283
app/routes/api.boxes.$deviceId.locations.ts	80.48%	60%	100%	89.18%	160, 167, 210, 215, 233, 244, 248, 252
app/routes/api.boxes.$deviceId.script.ts	76.66%	40%	80%	76.66%	203, 226-228, 236-243
app/routes/api.boxes.$deviceId.sensors.$sensorId.ts	79.41%	54.16%	100%	79.41%	137-139, 155, 161, 173, 182, 206, 211
app/routes/api.boxes.$deviceId.sensors.ts	77.77%	50%	100%	77.77%	119-121, 137, 143, 152, 159, 164
app/routes/api.boxes.$deviceId.ts	65.17%	53.48%	81.81%	66.66%	107-111, 279, 290, 304, 313-319, 325, 328, 341, 351, 357-364, 372, 376-378, 385-418, 442, 463, 467, 473, 481, 491-496, 504, 508, 523
app/routes/api.boxes.claim.ts	74.35%	36%	100%	76.31%	137, 143-145, 155, 167, 182, 199-209
app/routes/api.boxes.data.ts	87.5%	76.92%	80%	87.5%	254, 343-344, 353, 357-367
app/routes/api.boxes.transfer.$deviceId.ts	85.96%	68.42%	100%	92.3%	219, 233, 247-249, 253, 255, 283, 285, 333
app/routes/api.boxes.transfer.ts	81.25%	48.64%	100%	80.85%	229, 241, 263, 286, 303, 310, 327-337
app/routes/api.boxes.ts	95.23%	93.75%	100%	95.23%	198, 248
app/routes/api.sign-out.ts	88.88%	100%	100%	88.88%	45
app/routes/api.stats.ts	90.47%	83.33%	100%	90.47%	111, 116
app/routes/api.tags.ts	77.77%	50%	100%	77.77%	48, 53
app/routes/api.users.confirm-email.ts	73.33%	50%	100%	73.33%	17, 24-27, 31-33, 38
app/routes/api.users.me.boxes.$deviceId.ts	78.94%	62.5%	100%	78.94%	90, 97-99, 115, 121
app/routes/api.users.me.boxes.ts	86.66%	50%	100%	85.71%	106, 112
app/routes/api.users.me.resend-email-confirmation.ts	76.92%	50%	100%	76.92%	73-75, 80-82, 92
app/routes/api.users.me.ts	83.09%	78.04%	100%	85.5%	87-91, 268, 271, 297, 303, 317, 336, 359, 374, 379, 397, 408
app/routes/api.users.password-reset.ts	75%	54.54%	100%	75%	111, 147-163
app/routes/api.users.refresh-auth.ts	80.76%	71.42%	100%	83.33%	121, 130, 136, 150, 155
app/routes/api.users.register.ts	74.35%	47.61%	100%	74.35%	136-138, 144, 149, 160, 201, 206-217
app/routes/api.users.request-password-reset.ts	69.23%	25%	100%	69.23%	105, 113-125, 137, 150, 155
app/routes/api.users.sign-in.ts	85.71%	66.66%	100%	85.71%	125, 142, 146
app/services/device-service.server.ts	28.33%	20.68%	16.66%	29.09%	53, 64-69, 75-183, 201, 218, 240-243
app/services/statistics-service.server.ts	100%	100%	100%	100%
app/services/transfer-service.server.ts	70.37%	58.62%	100%	70.37%	30, 36-43, 59, 69, 73, 86, 90, 108, 118, 122, 142, 146-151, 177, 181, 195, 201
tests/data/generate_test_user.ts	100%	100%	100%	100%

Generated in workflow #2670 for commit b52c9cf by the Vitest Coverage Report Action

[socket-security]

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

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	zod-openapi@​5.4.6

View full report