Describing auth in OpenAPI clearly

Finally, someone tackling the securitySchemes object with the clarity it deserves. Too many OpenAPI specs I've inherited just dump a single bearer token under security and call it a day, leaving everyone guessing whether it's JWT, opaque, or something homemade with a salt shaker. The guide's breakdown of OAuth2 flows vs API keys vs HTTP Auth is exactly the kind of table-stakes reference that should be bookmarked by anyone who's ever had to debug a 401 in production. What I really appreciate is the emphasis on operation-level security over the global default. I've seen teams slap a global security: [{ bearerAuth: [] }] on the root and then wonder why their public health-check endpoint starts returning 403s. The article's practical tip about overriding security: [] for open routes is a lifesaver, especially when you're trying to document a hybrid public/private API. One thing I'd add: if you're using OpenAPI 3.1 (which is JSON Schema 2020-12 under the hood), you can now describe bearerFormat with more nuance, like specifying expected JWT claims or token expiration hints in the description field. The spec doesn't enforce it, but it saves hours of back-and-forth with frontend devs. Worth a read if you've ever had to explain why your scopes don't match the client's expectations or why flows need to be authorizationCode not implicit for production.