feat: improve Swagger authentication UX with Bearer scheme

[MaramMaruthiChethan]

Summary

This PR improves the Swagger/OpenAPI configuration by adding a proper
HTTP Bearer authentication scheme.

What was changed

• Added Bearer authentication to OpenAPI
• Enabled the Swagger "Authorize" button
• Clarified authentication flow using existing Open Food Facts accounts
• Prevented DB middleware from blocking /docs and /openapi.json

Why

Previously, Swagger UI did not provide a clear way to authenticate before
testing protected endpoints. This change makes authentication explicit
and usable for contributors, addressing issue #110.

Notes

Authentication relies on existing Open Food Facts user accounts.
No changes were made to the authentication logic itself.

[VaiTon]

What is this? You removed almost all the API routes...

[MaramMaruthiChethan]

Thanks for pointing that out — you were absolutely right 👍

That comment was based on an earlier commit where api.py was accidentally overwritten, which removed many routes. I’ve fixed that mistake and force-pushed a corrected commit.

Current state (commit a46a1f4):

• No API routes were removed
• Diff is minimal (+41 / −2)
• Only Swagger/OpenAPI UX was changed:
  • added HTTP Bearer security scheme for Swagger UI
  • enabled the “Authorize” button
  • skipped DB middleware for /docs, /openapi.json, /redoc

No authentication or business logic was modified.

Please let me know if you’d like me to split this into a smaller change or adjust anything further.

[areebahmeddd]

how did you test this? can you share any ss to validate?

[VaiTon]

@MaramMaruthiChethan I'm still not quite sure about what this PR does.

We already have the "Authenticate" button on https://api.folksonomy.openfoodfacts.org/docs (which, by the way, has an expired cert cc @alexgarel).

Maybe I'm missing something. Can you explain what we get by overriding the app.openapi object with a custom one?

[MaramMaruthiChethan]

Thanks for the questions — let me clarify what this PR does, why it changes OpenAPI generation, and how it was tested.
This PR does not change authentication logic, middleware behavior for API routes, or remove any endpoints. It is a documentation / Swagger UX improvement only.
Previously, Swagger UI showed an “Authenticate” button, but the authentication flow was implicit and unclear: protected endpoints were not explicitly marked as requiring a Bearer token in the OpenAPI spec, which caused confusion (as reported in issue #110). Contributors couldn’t clearly see that requests required an Authorization: Bearer header.
This PR makes that explicit by:
Declaring a standard HTTP Bearer security scheme in OpenAPI
Clearly marking protected endpoints as requiring authentication
Enabling a predictable “Authorize → Bearer token” flow in Swagger UI
Excluding /docs, /openapi.json, and /redoc from DB middleware so Swagger loads reliably
No business logic or auth validation was modified — only the generated OpenAPI schema.
Regarding app.openapi: FastAPI doesn’t provide a simpler built-in hook to globally define and apply a Bearer security scheme without duplicating dependencies. Overriding app.openapi is the recommended FastAPI approach when you need to customize security schemes while keeping runtime behavior unchanged. This affects documentation only, not request handling.
Testing:

Ran the API locally

Opened /docs and verified:

Bearer-based “Authorize” modal is present

Tokens are correctly injected as Authorization: Bearer

Protected endpoints show as secured

Swagger loads without DB-related errors

Confirmed the diff only affects OpenAPI security configuration (no routes added/removed)

If helpful, I can share before/after screenshots of the Swagger UI to validate the UX change.

Happy to adjust or simplify further if you’d prefer a different approach — thanks for the review 🙌