OpenAPI documentation mismatches with actual auth API behavior

[ikoral]

Summary
Several auth API endpoints have OpenAPI annotations (#[utoipa::path]) that don't match the actual handler behavior. I discovered these while building a SvelteKit frontend against TrailBase v0.23.9.

1. POST /api/auth/v1/reset_password/update/:password_reset_code
   Docs say: password_reset_code is a URL path parameter, response is 200.
   Actual behavior: The handler reads password_reset_code from the request body only (via Either), not from the URL path. The path parameter is ignored. Sending POST /api/auth/v1/reset_password/update/{code} returns 404. The working endpoint is POST /api/auth/v1/reset_password/update with the code in the JSON body. On success, it returns 303 (redirect), not 200.
   Source reference: — the annotation says path = "/reset_password/update/:password_reset_code" but reset_password_update_handler extracts from Either.
2. POST /api/auth/v1/register
   Docs say: Response is 200.
   Actual behavior: Returns 303 redirect on successful registration.
3. GET /api/auth/v1/verify_email/confirm/:email_verification_code
   Docs say: Response is 200.
   Actual behavior: Returns 302 or 303 redirect on successful verification.
4. POST /api/auth/v1/reset_password/request
   Docs say: Response is 200.
   Actual behavior: Returns a redirect on success (not 200).

Environment
TrailBase v0.23.9 (Docker: trailbase/trailbase:0.23.9)
trailbase JS client v0.9.0

[ignatz]

Thank you for the report 🙏 . I will fix this asap. Sadly, as you've already figured out they require manual synchronization

[ignatz]

Ok, so I gave this a go normalizing the behavior and codes across register, verify email, and reset password.

I'd love your input on a few items:

• redirects for both success and error handling is appropriate for HTML login forms but may be annoying for a more client-driven login UI. Any thoughts?
• I did a look a bit more in general redirect best-practices for login forms. Seems 302 is common practice for success, though axum seems to steer folks more towards 303, which is probably fine?
• I couldn't find any best practices for success vs failure redirects, e.g. register redirects now with a 307 on invalid passwords. At least it's a different code but not sure what's most ideal. Any preferences?
• Currently, the redirect targets (i.e. login and registration pages) are hard-coded for someone building their own UI, it may make sense to make them configurable. Similarly, if there's no hosted HTML auth UI (default or custom), falling back to 200s + 400s, may be preferable? Any thoughts?

Thanks for the report 🙏 - hope things are already in a somewhat better state, let me know

[ikoral]

Thanks 🙏 for the quick response. I am a bit busy this week, and usually I have more time for my side projects on Fridays and Saturdays. I will have a look as soon as I make some time.

I carefully read your questions again, and here are my two cents:

Redirects vs JSON: For SvelteKit/SPA, we use fetch and prefer JSON. Redirects are fine for HTML forms, but for API-style clients, we’d rather get 200/400 with JSON. A way to opt into that (e.g., Accept: application/json or a config flag) would be great.

302 vs 303: 303 is the right choice for success redirects. 302 is legacy and inconsistent. (AFAIK, and I also checked some experienced Svelte folks' answers in some forums for similar issues)

Success vs error redirects: Using 303 for success and 307 for errors makes sense. I think newer 307 is better since it keeps the method POST as POST and never turns into GET.

For SPAs, returning 400 + JSON on validation errors instead of redirecting would be even nicer for inline error handling.
Configurable targets: Yes, configurable redirect targets would help. We’d want to send users to our own /auth/logi,n etc., instead of the defaults.

PS: I am not an expert in this area; I just added what I am aware of. I asked codex but it generated toooooo many gibberish I don't understand, so I tried to write what makes sense to me. Maybe some other experienced folks can chime in and provide some advice.
Happy to test once available.